@synap-core/sdk 1.5.1 → 1.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synap-core/sdk",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "Type-safe tRPC client SDK for Synap data pods, public-door client, and server-only pod-app sign-in",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -55,11 +55,17 @@
     "dist",
     "src",
     "!src/__tests__",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "AGENTS.md"
   ],
   "engines": {
     "node": ">=20"
   },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
   "keywords": [
     "synap",
     "sdk",
@@ -91,10 +97,5 @@
     "url": "git+https://github.com/Synap-core/app-bases.git",
     "directory": "packages/sdk"
   },
-  "license": "MIT",
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
-  }
-}
+  "license": "MIT"
+}

package/src/connect/auth.ts

@@ -18,6 +18,11 @@
  * what the app may touch); without it a person already connected to that pod
  * goes straight to `next`. Either way a sign-in is a fresh PKCE + state flow.
  *
+ * `prompt=login` is the step-up: a credential door refused a stale device
+ * (`step_up_required`), so the person re-confirms at the POD (never through
+ * Synap Cloud) and the callback redeems the code with the connection's refresh
+ * token. Then retry the refused call once.
+ *
  * `connect` and `disconnect` change state, so they are POST and same-origin
  * only (Origin, else Sec-Fetch-Site): a third-party page cannot start a
  * sign-in into an attacker's pod for a visitor (login CSRF) or sign them out.
@@ -230,8 +235,10 @@ function isMockModeOrigin(origin: string): boolean {
 }
 
 /**
- * One `synap_requests[].permission`, refused here exactly when the pod would
- * refuse it: `<subject>[.<kind>].<action>`, lowercase, a kind only on
+ * One `synap_requests[].permission`, refused here when the pod would refuse
+ * it (at most as strict: any `https://<name>.synap.live` passes the review-verb
+ * check here, while the pod admits only its own list of Synap app ids, which
+ * this SDK does not copy; the pod's answer is the authority): `<subject>[.<kind>].<action>`, lowercase, a kind only on
  * `entity`, an action in the pod's grant actions (the review verbs only for a
  * Synap app, or on mock mode's loopback origin). Stricter on one point: no `*`
  * at all (`can()` matches exactly).
@@ -418,7 +425,7 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
   };
 
   /** Off to the pod's consent: fresh PKCE + state, the transaction cookie set (extra cookies first). */
-  async function toPod(opts: { pod: string; next: string; space: string | null; prompt: "consent" | null }, extra: string[] = []) {
+  async function toPod(opts: { pod: string; next: string; space: string | null; prompt: "consent" | "login" | null }, extra: string[] = []) {
     const started = await startConnect({
       ...flow,
       pod: opts.pod,
@@ -458,7 +465,9 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
     const pod = formField(form, "pod")?.slice(0, 512) ?? "";
     const next = safeNextPath(formField(form, "next"), origin) ?? paths.afterConnect;
     const space = formField(form, "space");
-    const prompt = formField(form, "prompt") === "consent" ? "consent" : null;
+    const asked = formField(form, "prompt");
+    // `login` is a step-up of the pod's own sign-in; it never goes through Synap Cloud (a Cloud sign-in never counts).
+    const prompt = asked === "consent" || asked === "login" ? asked : null;
     try {
       if (!prompt && (await liveConnectionTo(request, pod))) return redirect(new URL(next, origin).href);
       return await toPod({ pod, next, space, prompt });
@@ -476,6 +485,7 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
         ...flow,
         callbackUrl: request.url,
         transaction,
+        current: await store.read(request).catch(() => null),
         clientId,
         redirectUri,
         secret: config.secret,

package/src/connect/client.ts

@@ -66,8 +66,29 @@ export type PodErrorCode =
   | "pod_unreachable"
   /** The pod answered a redirect (a moved pod answers 308 from its old name): connect again at its new address. */
   | "pod_moved"
+  /**
+   * A credential door (approving a proposal that widens who or what can reach
+   * the pod) wants the person to re-confirm at the POD within 15 minutes; a
+   * Synap Cloud sign-in never counts. Recovery: `prompt_login`.
+   */
+  | "step_up_required"
+  /** Synap Cloud refused to vouch a person with no verified email. Recovery: `verify_email`. */
+  | "email_unverified"
+  /** Synap Cloud vouches an app origin over HTTPS only. Recovery: `use_https`. */
+  | "origin_insecure"
   | "server";
 
+/**
+ * What a typed refusal asks the app to do:
+ *  - `prompt_login`: send the person through the connect handler with
+ *    `prompt=login` (re-confirm at the pod; the SDK redeems it with the
+ *    device's refresh token), then retry ONCE;
+ *  - `verify_email`: tell the person to verify their Synap email;
+ *  - `use_https`: serve the app over HTTPS (`http://localhost` signs in to a
+ *    local Control Plane started with `CP_ALLOW_DEV_ORIGINS=true`, never to api.synap.live).
+ */
+export type PodRecovery = "prompt_login" | "verify_email" | "use_https";
+
 /**
  * Why the SDK refused before sending anything (`status: null`):
  *  - `agent_cannot_approve`: an agent connection asked to approve (the pod
@@ -86,6 +107,8 @@ export interface PodError {
   detail?: string;
   /** Set when the SDK refused locally (1.5). */
   reason?: PodRefusalReason;
+  /** What to do next, on `step_up_required`, `email_unverified` and `origin_insecure`. */
+  recovery?: PodRecovery;
   /**
    * On `unauthorized` (1.5): the pod refused the access token, the connection
    * still holds a refresh token, and this client could not renew it (no
@@ -297,14 +320,44 @@ function renewalError(err: unknown): PodError {
   }
 }
 
+/** The pod's step-up refusal (backend `STEP_UP_REQUIRED_MESSAGE`); the Hub's REST body carries only this text. */
+const STEP_UP_MESSAGE = "Confirm it's you before changing who or what can reach this pod.";
+
+/** The Control Plane's public problem codes (409, `{ error, code, recovery }`). */
+const CP_PROBLEMS: Readonly<Record<string, { code: PodErrorCode; recovery: PodRecovery }>> = {
+  CP_ACCOUNT_EMAIL_REQUIRED: { code: "email_unverified", recovery: "verify_email" },
+  FEDERATED_APPLICATION_ORIGIN_INSECURE: { code: "origin_insecure", recovery: "use_https" },
+};
+
+function isStepUp(obj: Record<string, unknown>): boolean {
+  const data = (v: unknown) => (v && typeof v === "object" ? (v as Record<string, unknown>) : {});
+  // tRPC shape (`error.data.reasonCode`), a flat reasonCode, or the Hub REST body: `{ error: <message> }`.
+  const nested = data(data(obj.error).data).reasonCode ?? data(obj.data).reasonCode ?? obj.reasonCode;
+  return nested === "STEP_UP_REQUIRED" || obj.error === STEP_UP_MESSAGE || obj.message === STEP_UP_MESSAGE;
+}
+
+/**
+ * A 403 or 409 body → its typed code. A step-up is read on a 403 only, a Control
+ * Plane problem on a 409 only; everything else keeps the plain `forbidden` /
+ * `door_unsupported` / `conflict`, so a typed refusal is never read as a generic one.
+ */
+export function classifyRefusal(status: 403 | 409 | number, body: unknown): { code: PodErrorCode; recovery?: PodRecovery } {
+  const obj = body && typeof body === "object" ? (body as Record<string, unknown>) : {};
+  if (status === 403) {
+    if (isStepUp(obj)) return { code: "step_up_required", recovery: "prompt_login" };
+    return { code: obj.code === "GRANT_DOOR_UNSUPPORTED" ? "door_unsupported" : "forbidden" };
+  }
+  const problem = typeof obj.code === "string" ? CP_PROBLEMS[obj.code] : undefined;
+  return problem ?? { code: "conflict" };
+}
+
 function errorFor(status: number, body: unknown, retryAfter: string | null, now: number): PodError {
   const obj = body && typeof body === "object" ? (body as Record<string, unknown>) : {};
   const detail = typeof obj.error === "string" ? obj.error : typeof obj.message === "string" ? obj.message : undefined;
   const base = { status, ...(detail !== undefined ? { detail } : {}) };
   if (status === 401) return { code: "unauthorized", ...base };
-  if (status === 403) return { code: obj.code === "GRANT_DOOR_UNSUPPORTED" ? "door_unsupported" : "forbidden", ...base };
+  if (status === 403 || status === 409) return { ...classifyRefusal(status, body), ...base };
   if (status === 404) return { code: "not_found", ...base };
-  if (status === 409) return { code: "conflict", ...base };
   if (status === 400 || status === 422) return { code: "invalid", ...base };
   if (status === 429) {
     const retryAfterSec = retryAfterSeconds(retryAfter, now);

package/src/connect/flow.ts

@@ -48,6 +48,8 @@ export interface ConnectTransaction {
   resource: string | null;
   /** A same-origin path to land on afterwards. */
   next: string | null;
+  /** The sign-in re-confirms a device that is already connected (`prompt=login`). */
+  stepUp?: boolean;
   createdAt: number;
 }
 
@@ -74,8 +76,13 @@ export interface StartConnectOptions extends FlowOptions {
    * `"consent"`: the person asked to see the consent screen again (to widen or
    * narrow what the app may touch). Sent as OIDC `prompt=consent`; the sign-in
    * is otherwise the same (fresh PKCE verifier and state).
+   *
+   * `"login"`: a step-up. A credential door refused a stale device
+   * (`step_up_required`): the person re-confirms at the pod (OIDC
+   * `prompt=login`) and the callback redeems the code WITH the connection's
+   * refresh token (`synap_device_refresh_token`; see `HandleCallbackOptions.current`).
    */
-  prompt?: "consent" | null;
+  prompt?: "consent" | "login" | null;
   allowInsecureLoopback?: boolean;
 }
 
@@ -124,7 +131,7 @@ export async function startConnect(opts: StartConnectOptions): Promise<StartedCo
   url.searchParams.set("code_challenge_method", "S256");
   if (resource) url.searchParams.set("resource", resource);
   if (opts.spaceHint) url.searchParams.set("synap_space_hint", opts.spaceHint);
-  if (opts.prompt === "consent") url.searchParams.set("prompt", "consent");
+  if (opts.prompt === "consent" || opts.prompt === "login") url.searchParams.set("prompt", opts.prompt);
 
   const tx: ConnectTransaction = {
     v: 1,
@@ -137,6 +144,7 @@ export async function startConnect(opts: StartConnectOptions): Promise<StartedCo
     verifier,
     resource,
     next: opts.next ?? null,
+    ...(opts.prompt === "login" ? { stepUp: true } : {}),
     createdAt: now,
   };
   const expiresAt = now + TRANSACTION_TTL_MS;
@@ -179,6 +187,13 @@ export interface HandleCallbackOptions extends FlowOptions {
   clientId: string;
   redirectUri: string;
   secret: AppSecret;
+  /**
+   * The connection this browser holds now. A step-up (`prompt=login`) of a
+   * Synap app's device is redeemed with ITS refresh token (the pod moves that
+   * device's clock instead of making a second device); without one, or for an
+   * app that is not a person's device, the code is redeemed as any other.
+   */
+  current?: PodConnection | null;
 }
 
 export interface CallbackResult {
@@ -219,6 +234,11 @@ export async function handleCallback(opts: HandleCallbackOptions): Promise<Callb
     code_verifier: tx.verifier,
   });
   if (tx.resource) body.set("resource", tx.resource);
+  const device =
+    tx.stepUp && opts.current && opts.current.actsAs === "person" && opts.current.podUrl === tx.issuer && opts.current.clientId === tx.clientId
+      ? opts.current
+      : null;
+  if (device?.refreshToken) body.set("synap_device_refresh_token", device.refreshToken);
   const json = await tokenRequest(tx.tokenEndpoint, body, "token", opts);
   const connection = parseTokenResponse(json, {
     podUrl: tx.issuer,
@@ -226,6 +246,7 @@ export async function handleCallback(opts: HandleCallbackOptions): Promise<Callb
     tokenEndpoint: tx.tokenEndpoint,
     revocationEndpoint: tx.revocationEndpoint,
     now: (opts.now ?? Date.now)(),
+    ...(device ? { previous: device } : {}),
   });
   return { connection, next: tx.next };
 }

package/src/connect/index.ts

@@ -30,6 +30,7 @@ export type {
   PodClientOptions,
   PodError,
   PodErrorCode,
+  PodRecovery,
   PodRefusalReason,
   PodResult,
   PodWriteResult,

package/src/testing/auth-server.ts

@@ -63,14 +63,32 @@ import type { MockPodSeed, MockSeedDocument, MockSeedFacet, MockSeedRelation, Mo
 /** A placeholder pod origin; never contacted. */
 export const MOCK_AUTH_ISSUER = "https://pod.mock-synap.test";
 
+/** Space -> readable kinds (null = all), what a token's `entity.*.read` grant rows add up to. */
+type ReadSpaces = ReadonlyMap<string, ReadonlySet<string> | null>;
+
 export const MOCK_GRANT: PodGrant[] = [
   { permission: "entity.post.read", workspaceId: "ws_mock_studio", workspaceName: "Studio" },
   { permission: "entity.post.create", workspaceId: "ws_mock_studio", workspaceName: "Studio" },
 ];
 
+/** The pod's step-up refusal text (backend `STEP_UP_REQUIRED_MESSAGE`). */
+const STEP_UP_MESSAGE = "Confirm it's you before changing who or what can reach this pod.";
+
 export const MOCK_USER: PodUser = { id: "user_mock_ada", name: "Ada Lovelace" };
 
-export type MockHubFailure = "rate_limited" | "forbidden" | "door_unsupported" | "unreachable" | "server" | "unavailable";
+export type MockHubFailure =
+  | "rate_limited"
+  | "forbidden"
+  | "door_unsupported"
+  /** 403 `{ error: <the pod's step-up message> }`: a stale device at a credential door (the Hub REST body has no reasonCode). */
+  | "step_up_required"
+  /** 409 problem `CP_ACCOUNT_EMAIL_REQUIRED` (Control Plane: no verified email). */
+  | "email_unverified"
+  /** 409 problem `FEDERATED_APPLICATION_ORIGIN_INSECURE` (Control Plane: an app origin that is not HTTPS). */
+  | "origin_insecure"
+  | "unreachable"
+  | "server"
+  | "unavailable";
 
 export interface MockAuthServerOptions {
   issuer?: string;
@@ -105,6 +123,14 @@ export interface MockAuthServerOptions {
    * not name it; the SDK reads an agent connection).
    */
   actsAs?: PodActsAs;
+  /**
+   * A Synap app's device starts STALE: `POST /proposals/:id/approve` is refused
+   * (403 `{ error: <step-up message> }`, the Hub REST shape) until the person
+   * re-confirms at the pod: `/authorize?prompt=login`, the code redeemed with the
+   * device's refresh token as `synap_device_refresh_token`. Needs `actsAs: "person"`.
+   * `expireStepUp()` makes it stale again (the 15-minute window).
+   */
+  requireStepUp?: boolean;
   /**
    * The pod's data as one JSON shape (`parseMockPodSeed`). `seed.entities` come
    * before `entities`; `seed.spaces` put a `templateSlug` on the grant rows of
@@ -175,6 +201,10 @@ export interface MockAuthServer {
   authorize(authorizeUrl: string, decision?: AuthorizeDecision): string;
   /** Mark a refresh token used elsewhere: presenting it now is a REUSE (family + live key revoked). */
   consumeRefreshToken(token: string): void;
+  /** The pod now says `synap_acts_as: v` (null = says nothing): the app left, or joined, the Synap list. */
+  setActsAs(v: PodActsAs | null): void;
+  /** The device's last real sign-in is older than the step-up window. */
+  expireStepUp(): void;
   /** The next refresh redeem loses a concurrent race: invalid_grant, nothing revoked. */
   loseNextRefreshRace(): void;
   /** Refresh-token redeems that were reuses (each revoked a family). */
@@ -198,6 +228,8 @@ interface CodeRow {
   challenge: string;
   resource: string | null;
   scope: string[];
+  /** `prompt=login` from a Synap app: its code re-confirms a device (and must come with its refresh token). */
+  stepUp: boolean;
 }
 
 interface AccessRow {
@@ -266,8 +298,8 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
    * role in one. The pod sends no role field on an entity row, so the mock takes
    * its roles as SEED input (`facets`) and answers them only when asked.
    */
-  function readableEntity(e: Record<string, unknown>, spaces: ReadonlySet<string>, only?: string | null): boolean {
-    if (typeof e.workspaceId === "string" && spaces.has(e.workspaceId) && (!only || e.workspaceId === only)) return true;
+  function readableEntity(e: Record<string, unknown>, spaces: ReadSpaces, only?: string | null): boolean {
+    if (typeof e.workspaceId === "string" && kindReadable(e, spaces, e.workspaceId) && (!only || e.workspaceId === only)) return true;
     // A pod-wide row is reached by any role in the space; a row of ANOTHER space only by a role stamped in this one.
     return facetsOf(e, spaces, only ?? undefined).some((f) => e.workspaceId == null || !f.sharedRole);
   }
@@ -276,8 +308,8 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
    * (backend `facetVisibilityConditions` under the token's grant), i.e. a role
    * whose seed space is granted; a workspace lens sees that space's roles only.
    */
-  const facetsOf = (e: Record<string, unknown>, spaces: ReadonlySet<string>, lens?: string): MockSeedFacet[] =>
-    rolesOf(e).filter((f) => typeof f.workspaceId === "string" && spaces.has(f.workspaceId) && (lens === undefined || f.workspaceId === lens));
+  const facetsOf = (e: Record<string, unknown>, spaces: ReadSpaces, lens?: string): MockSeedFacet[] =>
+    rolesOf(e).filter((f) => typeof f.workspaceId === "string" && kindReadable(e, spaces, f.workspaceId) && (lens === undefined || f.workspaceId === lens));
   /** backend `FacetRowAnnotation`: what `includeFacets=true` puts on a row. */
   const facetRow = (f: MockSeedFacet) => ({ facetId: f.facetId, slug: f.slug, properties: f.properties ?? {}, status: f.status ?? null });
   /** A row as the Hub answers it (`entityToWire`): roles ride on it only when asked. */
@@ -285,8 +317,29 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
     const { facets: _facets, facetSlugs: _facetSlugs, ...wire } = e;
     return wire;
   };
-  const readSpaces = (scope: readonly string[]): Set<string> =>
-    new Set(grant.filter((g) => /^entity\.(.+\.)?read$/.test(g.permission) && scope.includes(g.permission)).map((g) => g.workspaceId));
+  /**
+   * Space -> the kinds the token reads there (null = every kind), as the pod's
+   * kindClause: `entity.<kind>.read` narrows to that kind; `entity.read` and
+   * `entity.*.read` read all.
+   */
+  const readSpaces = (scope: readonly string[]): ReadSpaces => {
+    const out = new Map<string, Set<string> | null>();
+    for (const g of grant) {
+      const m = /^entity\.(?:(.+)\.)?read$/.exec(g.permission);
+      if (!m || !scope.includes(g.permission)) continue;
+      const kind = m[1];
+      if (kind === undefined || kind === "*") out.set(g.workspaceId, null);
+      else if (out.get(g.workspaceId) !== null) out.set(g.workspaceId, (out.get(g.workspaceId) ?? new Set<string>()).add(kind));
+      else continue;
+    }
+    return out;
+  };
+  /** Whether the token reads rows of `e`'s kind in `space`. */
+  const kindReadable = (e: Record<string, unknown>, spaces: ReadSpaces, space: string): boolean => {
+    if (!spaces.has(space)) return false;
+    const kinds = spaces.get(space);
+    return kinds === null || kinds === undefined ? kinds === null : kinds.has(String(e.profileSlug ?? e.type ?? ""));
+  };
   for (const p of seed.proposals ?? []) {
     proposals.push({
       proposalType: "create",
@@ -301,7 +354,11 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
       ...p,
     });
   }
-  const writeMode = options.writeMode ?? (options.actsAs === "person" ? "applied" : "proposed");
+  // What the pod says about the app, re-judged on every token response (`setActsAs` moves it).
+  let actsAs = options.actsAs;
+  const writeMode = () => options.writeMode ?? (actsAs === "person" ? "applied" : "proposed");
+  // A Synap app's device clock: stale until the person re-confirms at the pod (`requireStepUp`).
+  let deviceFresh = !options.requireStepUp;
   const graceMs = (options.refreshGraceSec ?? 30) * 1000;
   const app = options.app === undefined ? MOCK_APP : options.app;
   let proposalSeq = 0;
@@ -353,7 +410,7 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
         .map((g) => (g.templateSlug || !templateOf.has(g.workspaceId) ? g : { ...g, templateSlug: templateOf.get(g.workspaceId)! })),
       synap_user: user,
       ...(app ? { synap_app: app } : {}),
-      ...(options.actsAs ? { synap_acts_as: options.actsAs } : {}),
+      ...(actsAs ? { synap_acts_as: actsAs } : {}),
     };
     if (pair) {
       body.refresh_token = pair.refreshToken;
@@ -380,6 +437,25 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
       if (form.resource !== undefined && row.resource && form.resource !== row.resource) {
         return oauthError("invalid_target", "resource does not match the authorization request");
       }
+      // A Synap app's step-up (`routes.ts`): the code and the device's refresh token must agree.
+      if (actsAs === "person" && row.stepUp !== Boolean(form.synap_device_refresh_token)) {
+        return oauthError(
+          "invalid_grant",
+          row.stepUp
+            ? "This code re-confirms a device: send its refresh token as synap_device_refresh_token"
+            : "This code signs a new device in; a re-confirmation asks with prompt=login",
+        );
+      }
+      if (row.stepUp) {
+        const device = refreshTokens.get(form.synap_device_refresh_token!);
+        if (!device || device.clientId !== row.clientId || device.used || device.revoked) {
+          return oauthError("invalid_grant", "Invalid, expired, revoked or already-used refresh token");
+        }
+        // The device keeps its family: its clock moves, nothing else is made or ended.
+        device.used = true;
+        deviceFresh = true;
+        return json(200, tokenBody(row.scope, row.clientId, device.family));
+      }
       // The latest connect wins: a new code ends this client's older families.
       for (const r of refreshTokens.values()) if (r.clientId === row.clientId) revokeFamily(r.family);
       return json(200, tokenBody(row.scope, row.clientId, randomToken()));
@@ -467,6 +543,9 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
         const other = entities.find((e) => e.id === otherId);
         // As the pod: an edge whose far end is gone or out of the lens is not a neighbour.
         if (!other || !inLens(other) || !readableEntity(other, spaces)) continue;
+        // An edge between two pod-wide records is pod-wide (owner-only): not readable by a space-scoped app.
+        const self = entities.find((e) => e.id === id);
+        if (self && self.workspaceId == null && other.workspaceId == null) continue;
         connections.push({
           entityId: otherId,
           // relations.ts: the raw row plus its role slugs under the read's facet lens (a 1.5.0 seed's own facetSlugs otherwise).
@@ -606,6 +685,12 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
         return json(403, { error: "Forbidden" });
       case "door_unsupported":
         return json(403, { error: "This door is not available to a space-scoped key", code: "GRANT_DOOR_UNSUPPORTED" });
+      case "step_up_required":
+        return json(403, { error: STEP_UP_MESSAGE });
+      case "email_unverified":
+        return json(409, { error: "Add and verify an email on your Synap account to connect a pod.", code: "CP_ACCOUNT_EMAIL_REQUIRED", recovery: { action: "update_control_plane_profile" } });
+      case "origin_insecure":
+        return json(409, { error: "This application must be served over HTTPS to connect to a Pod.", code: "FEDERATED_APPLICATION_ORIGIN_INSECURE" });
       case "server":
         return json(500, { error: "Internal error" });
       case "unavailable":
@@ -669,9 +754,10 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
     const approve = method === "POST" ? /^\/proposals\/([^/]+)\/approve$/.exec(path) : null;
     if (approve) {
       // rejectAgentReviewer: an agent credential never approves, before anything is read.
-      if (options.actsAs !== "person") {
+      if (actsAs !== "person") {
         return json(403, { error: "An agent credential cannot approve proposals — approve is human review. Approve from a human session." });
       }
+      if (!deviceFresh) return json(403, { error: STEP_UP_MESSAGE });
       const p = proposals.find((x) => x.id === decodeURIComponent(approve[1]));
       if (!p) return json(404, { error: "Proposal not found" });
       // Only where the person granted proposal.approve, for the proposal's own space.
@@ -683,17 +769,29 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
       approvals.push(p.id);
       return json(200, { success: true, proposalId: p.id, proposal: { ...p } });
     }
-    // A pod-wide row's core fields are outside a space-scoped grant: refused (the pod: 403 or 404, not yet pinned), nothing written, no proposal.
+    // Roles: an app cannot add one to an existing entity (no grantable `facet.attach`), nor change one on a pod-wide record (`permits()` refuses null).
+    const attach = method === "POST" ? /^\/entities\/([^/]+)\/facets$/.exec(path) : null;
+    const facetPatch = method === "PATCH" ? /^\/facets\/([^/]+)$/.exec(path) : null;
+    if (attach) return json(403, { error: "grant does not allow" });
+    if (facetPatch) {
+      const fid = decodeURIComponent(facetPatch[1]);
+      const parent = entities.find((e) => rolesOf(e).some((f) => f.facetId === fid));
+      if (parent && parent.workspaceId == null) return json(403, { error: "grant does not allow" });
+    }
+    // A pod-wide row's core fields are outside a space-scoped grant: refused, nothing written, no proposal.
+    // The pod: 403 "grant does not allow" on the connected person's own record, 404 on a teammate's (outside the write floor).
     const patched = method === "PATCH" ? /^\/entities\/([^/]+)$/.exec(path) : null;
     if (patched) {
       const target = entities.find((e) => e.id === decodeURIComponent(patched[1]));
-      if (target && target.workspaceId == null) return json(403, { error: "grant does not allow" });
+      if (target && target.workspaceId == null) {
+        return typeof target.userId === "string" && target.userId !== user.id ? new Response(null, { status: 404 }) : json(403, { error: "grant does not allow" });
+      }
     }
     if (method !== "GET") {
       writes.push({ method, path, body });
       const fields = body && typeof body === "object" ? (body as Record<string, unknown>) : {};
       const workspaceId = typeof fields.workspaceId === "string" ? fields.workspaceId : null;
-      if (writeMode === "proposed") {
+      if (writeMode() === "proposed") {
         const proposalId = `prop_mock_${++proposalSeq}`;
         proposals.push({
           id: proposalId,
@@ -814,9 +912,15 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
       if (scope.length === 0) return finish({ error: "invalid_scope" });
       if (decision.deny) return finish({ error: "access_denied" });
       const code = randomToken();
-      codes.set(code, { clientId, redirectUri, challenge: q.get("code_challenge")!, resource, scope });
+      codes.set(code, { clientId, redirectUri, challenge: q.get("code_challenge")!, resource, scope, stepUp: actsAs === "person" && q.get("prompt") === "login" });
       return finish({ code });
     },
+    setActsAs(v) {
+      actsAs = v ?? undefined;
+    },
+    expireStepUp() {
+      deviceFresh = false;
+    },
     consumeRefreshToken(t) {
       const row = refreshTokens.get(t);
       if (row) row.used = true;