mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-18 08:02:12 +00:00
feat(api): say why a module's surfaces are not there, not only that they are not
`GET /api/auth/me` publishes a boolean per module, and three different situations collapse into the same `false`: the record has the module switched off, the active grant's sections do not open it, or the operator switched it off for the whole instance. A client holding the boolean has to guess between them, so the empty state either says nothing or says something that may be untrue -- offering a delegate a switch that is not theirs to reach, or telling an account holder to turn on a module the operator removed. `moduleAccess` carries the reason beside the booleans, which keep their exact meaning: `enabled`, `disabled`, `not_granted`, `unavailable`, resolved outside-in so the reason published is the one nothing further in can change. `modules[key]` stays exactly `moduleAccess[key] === "enabled"` for every key, and the two halves are built independently -- the boolean still runs through `maskModulesToSections` -- so the test of that pairing is an assertion rather than a restatement of a derivation. It is checked on the pure builder across a matrix of grants, records and operator blobs, and again on the real route for a scoped delegate, an unscoped one, and an operator-disabled module. Both ends in one change, because a payload field with no reader is the failure this repository keeps rediscovering. The reader is `ModuleDisabledNotice`, the shared module-off empty state the empty-states audit asks for: it names the reason in the reader's own language and offers the enable control only when the record's own switch is what is off, since neither of the other two is fixable from that page. The nutrients page adopts it and drops its bespoke block, which had been handing every delegate a button that would refuse them. Registered in the OpenAPI registry as `ModuleAccessMap` and carried on the account payload; the native contract gains a field and loses nothing, since a Bearer request carries no switch and never reads `not_granted`.
This commit is contained in:
1 parent
0c46df1413
commit
47a5079cfa
17 files changed
+859
-21
No files matched your search
@@ -34,6 +34,7 @@ import {
|
||||
inviteManagedProfileGuardianSchema,
|
||||
updateManagedProfileSchema,
|
||||
} from "@/lib/validations/managed-profiles";
|
||||
import { moduleAccessMap } from "./profile";
|
||||
import { dataEnvelope, errorEnvelope, stdResponses } from "./shared";
|
||||
|
||||
/**
|
||||
@@ -448,12 +449,13 @@ const accountPayload = z
|
||||
id: z.string(),
|
||||
username: z.string(),
|
||||
accountAccess: accountAccessBlock,
|
||||
moduleAccess: moduleAccessMap,
|
||||
recordSession: recordSessionState.nullable(),
|
||||
})
|
||||
.meta({
|
||||
id: "AccountPayload",
|
||||
description:
|
||||
"The signed-in account: its identity, its preferences, and (since v1.36.0) what account sharing lets it do. Additional properties are the preference fields this spec does not yet enumerate. Under an active switch the identity and preference fields still describe the CALLER, because display preferences belong to the person at the keyboard rather than to the record they are reading. Two fields are the exception (v1.38.14): `modules` and `cycleTrackingEnabled` describe the ACTIVE RECORD, since every surface they gate shows the record's data — and they are masked to the sections the active grant opens, so a scoped grant reads `false` for a module outside it rather than the record's true state. With no switch — which is every native request, since the Bearer transport carries none — the two are the same account and nothing is masked.",
|
||||
"The signed-in account: its identity, its preferences, and (since v1.36.0) what account sharing lets it do. Additional properties are the preference fields this spec does not yet enumerate. Under an active switch the identity and preference fields still describe the CALLER, because display preferences belong to the person at the keyboard rather than to the record they are reading. Two fields are the exception (v1.38.14): `modules` and `cycleTrackingEnabled` describe the ACTIVE RECORD, since every surface they gate shows the record's data — and they are masked to the sections the active grant opens, so a scoped grant reads `false` for a module outside it rather than the record's true state. With no switch — which is every native request, since the Bearer transport carries none — the two are the same account and nothing is masked. `moduleAccess` says WHY each module is or is not there — the record's own switch, the edge of the grant, or the operator's instance-wide one — beside the `modules` booleans it never contradicts.",
|
||||
});
|
||||
|
||||
/**
|
||||
|
||||
@@ -87,6 +87,32 @@ const moduleMapResolved = z
|
||||
"Fully-resolved module enable/disable map. Every toggleable module key is present. `false` means the surface should disappear end-to-end (nav, dashboard, insights, …). `cycle` mirrors `cycleTrackingEnabled`; `coach` mirrors the resolved per-user opt-out + operator master flag. On `GET /api/auth/me` it answers for the RECORD the session is inside rather than for the caller, because every surface it gates shows the record's data, and it is masked to the sections the active grant opens — a module outside them reads `false` rather than the record's true state. With no switch — which is every native request, since the Bearer transport carries none — the two are the same account, nothing is masked and the payload is unchanged.",
|
||||
});
|
||||
|
||||
/**
|
||||
* The same answer as `ModuleMap`, with the reason attached.
|
||||
*
|
||||
* Additive and beside the booleans, which keep their meaning: for every key
|
||||
* `modules[key]` is exactly `moduleAccess[key] === "enabled"`. A client that
|
||||
* only gates a surface keeps reading the boolean; a client that has to TELL
|
||||
* somebody why a surface is missing reads this, because the boolean collapses
|
||||
* three different situations into one `false`.
|
||||
*/
|
||||
export const moduleAccessMap = z
|
||||
.object(
|
||||
Object.fromEntries(
|
||||
MODULE_KEYS.map((k) => [
|
||||
k,
|
||||
z
|
||||
.enum(["enabled", "disabled", "not_granted", "unavailable"])
|
||||
.describe(`Why the "${k}" module is or is not available here.`),
|
||||
]),
|
||||
),
|
||||
)
|
||||
.meta({
|
||||
id: "ModuleAccessMap",
|
||||
description:
|
||||
"Why each toggleable module is or is not available for the record this session is inside. `enabled` — the module is on and the client may paint it. `disabled` — the record has it switched off. `not_granted` — the active grant's sections do not open the module's section, which also covers every module that reads across the whole record (achievements, the assistant surfaces, the export, environment, the account's own MCP endpoint) since no scoped grant opens one. `unavailable` — the operator switched the module off for the whole instance. Precedence, highest first: `unavailable` > `not_granted` > `disabled` > `enabled`, so the reason published is the one nothing further in can change. Own-record sessions and unscoped grants never produce `not_granted`. Every key is present, and `modules[key] === (moduleAccess[key] === \"enabled\")` holds for every key — this field adds a reason, never a different gate.",
|
||||
});
|
||||
|
||||
const moduleMapEnvelopeInner = z
|
||||
.object({ modules: moduleMapResolved, updatedAt: updatedAtTokenField })
|
||||
.meta({ id: "ModulesResponse" });
|
||||
|
||||
@@ -0,0 +1,152 @@
|
||||
/**
|
||||
* The two maps `GET /api/auth/me` publishes for a record, and the one thing
|
||||
* that must stay true between them.
|
||||
*
|
||||
* `modules` is the boolean gate every client already reads; `moduleAccess` is
|
||||
* the same answer with its reason attached. They are built independently in
|
||||
* `buildModuleDisclosure` — the boolean half still runs through
|
||||
* `maskModulesToSections` — precisely so this file can assert they agree
|
||||
* rather than restate a derivation. Delete the mask from either half and the
|
||||
* invariant leg goes red.
|
||||
*/
|
||||
import { describe, it, expect } from "vitest";
|
||||
|
||||
import { MODULE_KEYS, type ModuleKey } from "@/lib/modules/registry";
|
||||
import type { ShareDomain } from "@/lib/sharing/scope";
|
||||
|
||||
import {
|
||||
MODULE_SHARE_DOMAIN,
|
||||
buildModuleDisclosure,
|
||||
} from "../module-disclosure";
|
||||
|
||||
function allModules(value: boolean): Record<ModuleKey, boolean> {
|
||||
return Object.fromEntries(MODULE_KEYS.map((k) => [k, value])) as Record<
|
||||
ModuleKey,
|
||||
boolean
|
||||
>;
|
||||
}
|
||||
|
||||
const AVAILABLE = allModules(true);
|
||||
|
||||
describe("buildModuleDisclosure", () => {
|
||||
it("answers enabled / disabled only for a record with no grant over it", () => {
|
||||
const resolved = { ...allModules(true), mood: false, labs: false };
|
||||
|
||||
const { moduleAccess } = buildModuleDisclosure(resolved, AVAILABLE, null);
|
||||
|
||||
expect(moduleAccess.mood).toBe("disabled");
|
||||
expect(moduleAccess.labs).toBe("disabled");
|
||||
expect(moduleAccess.sleep).toBe("enabled");
|
||||
expect(new Set(Object.values(moduleAccess))).toEqual(
|
||||
new Set(["enabled", "disabled"]),
|
||||
);
|
||||
});
|
||||
|
||||
it("marks the sections a scoped grant does not open as not_granted", () => {
|
||||
const sections: ShareDomain[] = ["measurements"];
|
||||
|
||||
const { moduleAccess } = buildModuleDisclosure(
|
||||
allModules(true),
|
||||
AVAILABLE,
|
||||
sections,
|
||||
);
|
||||
|
||||
// Inside the grant.
|
||||
expect(moduleAccess.sleep).toBe("enabled");
|
||||
expect(moduleAccess.glucose).toBe("enabled");
|
||||
// A section the grant does not name.
|
||||
expect(moduleAccess.labs).toBe("not_granted");
|
||||
expect(moduleAccess.cycle).toBe("not_granted");
|
||||
// Record-spanning: no scoped grant opens a module with a null domain, so
|
||||
// the answer is the same one the boolean mask gives.
|
||||
for (const key of MODULE_KEYS) {
|
||||
if (MODULE_SHARE_DOMAIN[key] === null) {
|
||||
expect(moduleAccess[key], key).toBe("not_granted");
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it("never says not_granted for an unscoped grant or an own record", () => {
|
||||
// `null` sections are both cases at once: an own-record session has no
|
||||
// grant to narrow to, and an unscoped grant names the whole record.
|
||||
const { moduleAccess } = buildModuleDisclosure(
|
||||
{ ...allModules(true), coach: false },
|
||||
AVAILABLE,
|
||||
null,
|
||||
);
|
||||
expect(Object.values(moduleAccess)).not.toContain("not_granted");
|
||||
expect(moduleAccess.coach).toBe("disabled");
|
||||
});
|
||||
|
||||
it("lets the operator's instance-wide switch outrank every other reason", () => {
|
||||
const operator = { ...AVAILABLE, labs: false, sleep: false };
|
||||
// The resolved map already has the operator layer AND-ed in, which is why
|
||||
// an operator-off module arrives here as `false` and would otherwise be
|
||||
// indistinguishable from the record's own choice.
|
||||
const resolved = { ...allModules(true), labs: false, sleep: false };
|
||||
|
||||
// Off for the record's own session…
|
||||
const own = buildModuleDisclosure(resolved, operator, null);
|
||||
expect(own.moduleAccess.labs).toBe("unavailable");
|
||||
|
||||
// …and still the operator's switch under a grant that does not open the
|
||||
// section, because the switch that would have to move is theirs either way.
|
||||
const scoped = buildModuleDisclosure(resolved, operator, ["measurements"]);
|
||||
expect(scoped.moduleAccess.labs).toBe("unavailable");
|
||||
expect(scoped.moduleAccess.sleep).toBe("unavailable");
|
||||
expect(scoped.moduleAccess.cycle).toBe("not_granted");
|
||||
});
|
||||
|
||||
it("keeps modules[key] equal to moduleAccess[key] === enabled everywhere", () => {
|
||||
const sectionSets: Array<readonly ShareDomain[] | null> = [
|
||||
null,
|
||||
[],
|
||||
["measurements"],
|
||||
["measurements", "labs"],
|
||||
["cycle", "mind", "medications", "illness", "documents", "profile"],
|
||||
];
|
||||
const resolvedMaps = [
|
||||
allModules(true),
|
||||
allModules(false),
|
||||
{ ...allModules(true), mood: false, cycle: false, medications: false },
|
||||
];
|
||||
const operatorMaps = [
|
||||
AVAILABLE,
|
||||
allModules(false),
|
||||
{ ...AVAILABLE, insights: false, mood: false },
|
||||
];
|
||||
|
||||
let checked = 0;
|
||||
for (const sections of sectionSets) {
|
||||
for (const resolved of resolvedMaps) {
|
||||
for (const operator of operatorMaps) {
|
||||
// The operator layer is AND-ed into the resolved map upstream; mirror
|
||||
// that here or the fixture would describe a state the gate cannot
|
||||
// produce.
|
||||
const effective = Object.fromEntries(
|
||||
MODULE_KEYS.map((k) => [k, resolved[k] && operator[k]]),
|
||||
) as Record<ModuleKey, boolean>;
|
||||
const { modules, moduleAccess } = buildModuleDisclosure(
|
||||
effective,
|
||||
operator,
|
||||
sections,
|
||||
);
|
||||
for (const key of MODULE_KEYS) {
|
||||
expect(
|
||||
modules[key],
|
||||
`${key} under sections=${JSON.stringify(sections)}`,
|
||||
).toBe(moduleAccess[key] === "enabled");
|
||||
checked += 1;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
expect(checked).toBe(
|
||||
sectionSets.length *
|
||||
resolvedMaps.length *
|
||||
operatorMaps.length *
|
||||
MODULE_KEYS.length,
|
||||
);
|
||||
expect(checked).toBeGreaterThan(0);
|
||||
});
|
||||
});
|
||||
@@ -26,7 +26,11 @@
|
||||
* own route inventory gives them: `/`, `/achievements` and the narrative
|
||||
* surfaces read across sections, and a selected-domain grant never opens one.
|
||||
*/
|
||||
import { MODULE_KEYS, type ModuleKey } from "@/lib/modules/registry";
|
||||
import {
|
||||
MODULE_KEYS,
|
||||
isCodeDisabledModule,
|
||||
type ModuleKey,
|
||||
} from "@/lib/modules/registry";
|
||||
import type { ShareDomain } from "@/lib/sharing/scope";
|
||||
|
||||
/**
|
||||
@@ -102,3 +106,94 @@ export function maskModulesToSections(
|
||||
}
|
||||
return masked;
|
||||
}
|
||||
|
||||
/**
|
||||
* Why a module's surfaces are not there.
|
||||
*
|
||||
* The boolean map answers "paint it or not", which is all a gate needs and
|
||||
* strictly less than a person needs. Three different situations collapse into
|
||||
* the same `false`: the record has the module switched off, the grant this
|
||||
* session is inside does not cover it, and the operator turned it off for the
|
||||
* whole instance. A client holding only the boolean has to guess between them,
|
||||
* so the empty state either says nothing or says something that may be untrue —
|
||||
* offering a delegate a switch they cannot reach, or telling an account to turn
|
||||
* on a module the operator removed.
|
||||
*
|
||||
* `enabled` is the module the client may paint. `disabled` is the record's own
|
||||
* switch. `not_granted` is the mask above: the active grant's sections do not
|
||||
* open this module's section, or the module reads across the record and no
|
||||
* scoped grant opens one. `unavailable` is the operator's instance-wide switch.
|
||||
*/
|
||||
export type ModuleAccessState =
|
||||
"enabled" | "disabled" | "not_granted" | "unavailable";
|
||||
|
||||
/**
|
||||
* Precedence, highest first: `unavailable` > `not_granted` > `disabled` >
|
||||
* `enabled`. It runs outside-in — what the operator decided, then what the
|
||||
* grant opens, then what the record chose — so the reason a client shows is
|
||||
* the one nothing further in can change. An operator-disabled module reads
|
||||
* `unavailable` for a delegate too, rather than `not_granted`, because the
|
||||
* switch that would have to move is the operator's either way.
|
||||
*/
|
||||
function resolveModuleAccess(
|
||||
key: ModuleKey,
|
||||
modules: Record<ModuleKey, boolean>,
|
||||
operatorAvailability: Record<ModuleKey, boolean>,
|
||||
sections: readonly ShareDomain[] | null,
|
||||
): ModuleAccessState {
|
||||
// The instance layer, both halves of it: the operator's availability blob
|
||||
// and the code-level hard-off. `CODE_DISABLED_MODULE_KEYS` is empty today,
|
||||
// so this term changes no answer; it is here because a module switched off
|
||||
// in code is not available on this instance either, and without it such a
|
||||
// module would report itself as the record's own choice.
|
||||
if (isCodeDisabledModule(key) || operatorAvailability[key] === false) {
|
||||
return "unavailable";
|
||||
}
|
||||
const domain = MODULE_SHARE_DOMAIN[key];
|
||||
if (
|
||||
sections !== null &&
|
||||
(domain === null || !sectionsOpen(sections, domain))
|
||||
) {
|
||||
return "not_granted";
|
||||
}
|
||||
return modules[key] ? "enabled" : "disabled";
|
||||
}
|
||||
|
||||
/** Both maps the account payload publishes for the active record. */
|
||||
export interface ModuleDisclosure {
|
||||
/** The boolean gate map, masked to the grant. Unchanged semantics. */
|
||||
modules: Record<ModuleKey, boolean>;
|
||||
/** The same answer with its reason attached. */
|
||||
moduleAccess: Record<ModuleKey, ModuleAccessState>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Build both maps for one record, as one grant may read them.
|
||||
*
|
||||
* The two halves are computed independently rather than one derived from the
|
||||
* other, and that is deliberate: `modules[key] === (moduleAccess[key] ===
|
||||
* "enabled")` is the contract every client leans on, and deriving one from the
|
||||
* other would turn the test of it into a tautology. `modules` keeps running
|
||||
* through {@link maskModulesToSections}, byte for byte what it was.
|
||||
*
|
||||
* `modules` is the ALREADY-RESOLVED map (`resolveModuleMap`), which has the
|
||||
* operator layer AND-ed in; `operatorAvailability` is that layer on its own
|
||||
* (`getOperatorModuleAvailability`), which is what makes the operator's
|
||||
* decision separable from the record's.
|
||||
*/
|
||||
export function buildModuleDisclosure(
|
||||
modules: Record<ModuleKey, boolean>,
|
||||
operatorAvailability: Record<ModuleKey, boolean>,
|
||||
sections: readonly ShareDomain[] | null,
|
||||
): ModuleDisclosure {
|
||||
const moduleAccess = {} as Record<ModuleKey, ModuleAccessState>;
|
||||
for (const key of MODULE_KEYS) {
|
||||
moduleAccess[key] = resolveModuleAccess(
|
||||
key,
|
||||
modules,
|
||||
operatorAvailability,
|
||||
sections,
|
||||
);
|
||||
}
|
||||
return { modules: maskModulesToSections(modules, sections), moduleAccess };
|
||||
}
|
||||
Reference in new issue
Block a user