@synap-core/sdk 1.5.0 → 1.5.2

package/dist/testing.d.cts

@@ -51,14 +51,63 @@ declare const MOCK_SITE: MockSite;
  * `relations` as graph edges for `GET /entities/:id/connections`, `proposals`
  * as `GET /proposals?view=basic` rows, `spaces` name each granted space's
  * template (`synap_grant[].templateSlug` on the token response).
+ *
+ * An entity's roles ride on its row as `facets`, the shape `GET /entities?
+ * includeFacets=true` answers them (`{ facetId, slug, properties, status }`),
+ * plus the seed-only space each is stamped in, so a seed row reads like a pod
+ * row read with includeFacets. The mock derives `facetSlugs` and the reach rule
+ * from them and serves neither field unless asked, as the pod.
  */
 
+/** One role an entity wears (backend `FacetRowAnnotation`, plus the space it is stamped in). */
+interface MockSeedFacet {
+    facetId: string;
+    /** The role's slug, e.g. `lead`. */
+    slug: string;
+    /** The facet's overlay properties. Default `{}`. */
+    properties?: Record<string, unknown>;
+    /** Its lifecycle status. Default null. */
+    status?: string | null;
+    /**
+     * Seed only, never served: the space the role is in, i.e. the space whose
+     * members see the facet (stamped there, or a pod-wide facet of a role granted
+     * to it). A role in a granted space puts a pod-wide entity in the app's
+     * reach; a workspace lens sees the roles of that space only.
+     */
+    workspaceId: string;
+    /**
+     * Seed only, never served: the role is SHARED, i.e. stored pod-wide (null
+     * `workspaceId`) and granted to `workspaceId`, which then means "the space it
+     * is granted to". Default false = stamped in `workspaceId`. The pod treats the
+     * two alike for reach, except `includePodWide=false` on a space lens, which
+     * drops a pod-wide row reached only through a shared role.
+     */
+    sharedRole?: boolean;
+}
 interface MockSeedEntity {
     id: string;
     profileSlug?: string;
     workspaceId?: string | null;
     title?: string | null;
     properties?: Record<string, unknown>;
+    /**
+     * The roles (facets) it wears, in the wire shape plus the space each is in
+     * (`MockSeedFacet`). SEED INPUT ONLY: the pod sends them only to
+     * `includeFacets`, and so does the mock. A pod-wide entity (`workspaceId:
+     * null`) with a role in a granted space is readable by the app, as a member
+     * of that space sees it. Absent = none.
+     */
+    facets?: MockSeedFacet[];
+    /**
+     * @deprecated Use `facets`; removed in 2.0. Shorthand for `facets` entries
+     * with no id and no overlay: `parseMockPodSeed` turns each into a facet (a
+     * generated `facetId`, empty properties, a null status). A role stated in
+     * both is refused.
+     */
+    seedRoles?: Array<{
+        profileSlug: string;
+        workspaceId: string;
+    }>;
     [key: string]: unknown;
 }
 interface MockSeedSession {
@@ -123,7 +172,13 @@ declare function parseMockPodSeed(input: string | unknown): MockPodSeed;
 declare const MOCK_AUTH_ISSUER = "https://pod.mock-synap.test";
 declare const MOCK_GRANT: PodGrant[];
 declare const MOCK_USER: PodUser;
-type MockHubFailure = "rate_limited" | "forbidden" | "door_unsupported" | "unreachable" | "server" | "unavailable";
+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";
 interface MockAuthServerOptions {
     issuer?: string;
     /** Issue rotating refresh tokens. Default true; false = a pod without refresh tokens. */
@@ -160,6 +215,14 @@ 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
@@ -235,6 +298,10 @@ 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). */
@@ -361,4 +428,4 @@ interface MockPod {
 }
 declare function createMockPod(options?: MockPodOptions): MockPod;
 
-export { type AuthorizeDecision, MOCK_APP, MOCK_APP_AGENT_ID, MOCK_AUTH_ISSUER, MOCK_CLOUD_URL, MOCK_FAILURE_TOKENS, MOCK_FORM, MOCK_GRANT, MOCK_HTML_SHARE, MOCK_POD_URL, MOCK_RETRY_AFTER_SEC, MOCK_SHARE, MOCK_SITE, MOCK_TOKENS, MOCK_USER, type MockAuthRequest, type MockAuthServer, type MockAuthServerOptions, type MockCloud, type MockCollection, type MockHubFailure, type MockPod, type MockPodOptions, type MockPodSeed, type MockProposal, type MockRequest, type MockSeedDocument, type MockSeedEntity, type MockSeedRelation, type MockSeedSession, type MockSeedSpace, type MockSite, type MockSubmission, createMockAuthServer, createMockCloud, createMockPod, parseMockPodSeed };
+export { type AuthorizeDecision, MOCK_APP, MOCK_APP_AGENT_ID, MOCK_AUTH_ISSUER, MOCK_CLOUD_URL, MOCK_FAILURE_TOKENS, MOCK_FORM, MOCK_GRANT, MOCK_HTML_SHARE, MOCK_POD_URL, MOCK_RETRY_AFTER_SEC, MOCK_SHARE, MOCK_SITE, MOCK_TOKENS, MOCK_USER, type MockAuthRequest, type MockAuthServer, type MockAuthServerOptions, type MockCloud, type MockCollection, type MockHubFailure, type MockPod, type MockPodOptions, type MockPodSeed, type MockProposal, type MockRequest, type MockSeedDocument, type MockSeedEntity, type MockSeedFacet, type MockSeedRelation, type MockSeedSession, type MockSeedSpace, type MockSite, type MockSubmission, createMockAuthServer, createMockCloud, createMockPod, parseMockPodSeed };

package/dist/testing.d.ts

@@ -51,14 +51,63 @@ declare const MOCK_SITE: MockSite;
  * `relations` as graph edges for `GET /entities/:id/connections`, `proposals`
  * as `GET /proposals?view=basic` rows, `spaces` name each granted space's
  * template (`synap_grant[].templateSlug` on the token response).
+ *
+ * An entity's roles ride on its row as `facets`, the shape `GET /entities?
+ * includeFacets=true` answers them (`{ facetId, slug, properties, status }`),
+ * plus the seed-only space each is stamped in, so a seed row reads like a pod
+ * row read with includeFacets. The mock derives `facetSlugs` and the reach rule
+ * from them and serves neither field unless asked, as the pod.
  */
 
+/** One role an entity wears (backend `FacetRowAnnotation`, plus the space it is stamped in). */
+interface MockSeedFacet {
+    facetId: string;
+    /** The role's slug, e.g. `lead`. */
+    slug: string;
+    /** The facet's overlay properties. Default `{}`. */
+    properties?: Record<string, unknown>;
+    /** Its lifecycle status. Default null. */
+    status?: string | null;
+    /**
+     * Seed only, never served: the space the role is in, i.e. the space whose
+     * members see the facet (stamped there, or a pod-wide facet of a role granted
+     * to it). A role in a granted space puts a pod-wide entity in the app's
+     * reach; a workspace lens sees the roles of that space only.
+     */
+    workspaceId: string;
+    /**
+     * Seed only, never served: the role is SHARED, i.e. stored pod-wide (null
+     * `workspaceId`) and granted to `workspaceId`, which then means "the space it
+     * is granted to". Default false = stamped in `workspaceId`. The pod treats the
+     * two alike for reach, except `includePodWide=false` on a space lens, which
+     * drops a pod-wide row reached only through a shared role.
+     */
+    sharedRole?: boolean;
+}
 interface MockSeedEntity {
     id: string;
     profileSlug?: string;
     workspaceId?: string | null;
     title?: string | null;
     properties?: Record<string, unknown>;
+    /**
+     * The roles (facets) it wears, in the wire shape plus the space each is in
+     * (`MockSeedFacet`). SEED INPUT ONLY: the pod sends them only to
+     * `includeFacets`, and so does the mock. A pod-wide entity (`workspaceId:
+     * null`) with a role in a granted space is readable by the app, as a member
+     * of that space sees it. Absent = none.
+     */
+    facets?: MockSeedFacet[];
+    /**
+     * @deprecated Use `facets`; removed in 2.0. Shorthand for `facets` entries
+     * with no id and no overlay: `parseMockPodSeed` turns each into a facet (a
+     * generated `facetId`, empty properties, a null status). A role stated in
+     * both is refused.
+     */
+    seedRoles?: Array<{
+        profileSlug: string;
+        workspaceId: string;
+    }>;
     [key: string]: unknown;
 }
 interface MockSeedSession {
@@ -123,7 +172,13 @@ declare function parseMockPodSeed(input: string | unknown): MockPodSeed;
 declare const MOCK_AUTH_ISSUER = "https://pod.mock-synap.test";
 declare const MOCK_GRANT: PodGrant[];
 declare const MOCK_USER: PodUser;
-type MockHubFailure = "rate_limited" | "forbidden" | "door_unsupported" | "unreachable" | "server" | "unavailable";
+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";
 interface MockAuthServerOptions {
     issuer?: string;
     /** Issue rotating refresh tokens. Default true; false = a pod without refresh tokens. */
@@ -160,6 +215,14 @@ 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
@@ -235,6 +298,10 @@ 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). */
@@ -361,4 +428,4 @@ interface MockPod {
 }
 declare function createMockPod(options?: MockPodOptions): MockPod;
 
-export { type AuthorizeDecision, MOCK_APP, MOCK_APP_AGENT_ID, MOCK_AUTH_ISSUER, MOCK_CLOUD_URL, MOCK_FAILURE_TOKENS, MOCK_FORM, MOCK_GRANT, MOCK_HTML_SHARE, MOCK_POD_URL, MOCK_RETRY_AFTER_SEC, MOCK_SHARE, MOCK_SITE, MOCK_TOKENS, MOCK_USER, type MockAuthRequest, type MockAuthServer, type MockAuthServerOptions, type MockCloud, type MockCollection, type MockHubFailure, type MockPod, type MockPodOptions, type MockPodSeed, type MockProposal, type MockRequest, type MockSeedDocument, type MockSeedEntity, type MockSeedRelation, type MockSeedSession, type MockSeedSpace, type MockSite, type MockSubmission, createMockAuthServer, createMockCloud, createMockPod, parseMockPodSeed };
+export { type AuthorizeDecision, MOCK_APP, MOCK_APP_AGENT_ID, MOCK_AUTH_ISSUER, MOCK_CLOUD_URL, MOCK_FAILURE_TOKENS, MOCK_FORM, MOCK_GRANT, MOCK_HTML_SHARE, MOCK_POD_URL, MOCK_RETRY_AFTER_SEC, MOCK_SHARE, MOCK_SITE, MOCK_TOKENS, MOCK_USER, type MockAuthRequest, type MockAuthServer, type MockAuthServerOptions, type MockCloud, type MockCollection, type MockHubFailure, type MockPod, type MockPodOptions, type MockPodSeed, type MockProposal, type MockRequest, type MockSeedDocument, type MockSeedEntity, type MockSeedFacet, type MockSeedRelation, type MockSeedSession, type MockSeedSpace, type MockSite, type MockSubmission, createMockAuthServer, createMockCloud, createMockPod, parseMockPodSeed };

package/dist/testing.js

@@ -120,12 +120,27 @@ var MOCK_SITE = {
   }
 };
 
+// src/testing/roles.ts
+function desugarSeedRoles(row, at) {
+  if (!Array.isArray(row.seedRoles)) return row;
+  const { seedRoles, ...rest } = row;
+  const facets = Array.isArray(row.facets) ? row.facets : [];
+  const shorthand = seedRoles.filter((r) => typeof r?.profileSlug === "string" && typeof r.workspaceId === "string").map((r, i) => ({ facetId: `seedrole_${String(row.id)}_${i}`, slug: r.profileSlug, workspaceId: r.workspaceId }));
+  for (const r of shorthand) {
+    if (facets.some((f) => f?.slug === r.slug && f.workspaceId === r.workspaceId)) {
+      throw new TypeError(`${at} ("${String(row.id)}"): the role "${r.slug}" in ${r.workspaceId} is in both facets and seedRoles; keep it in facets only`);
+    }
+  }
+  return { ...rest, facets: [...facets, ...shorthand] };
+}
+
 // src/testing/auth-server.ts
 var MOCK_AUTH_ISSUER = "https://pod.mock-synap.test";
 var MOCK_GRANT = [
   { permission: "entity.post.read", workspaceId: "ws_mock_studio", workspaceName: "Studio" },
   { permission: "entity.post.create", workspaceId: "ws_mock_studio", workspaceName: "Studio" }
 ];
+var STEP_UP_MESSAGE = "Confirm it's you before changing who or what can reach this pod.";
 var MOCK_USER = { id: "user_mock_ada", name: "Ada Lovelace" };
 var MOCK_APP = { id: "app_mock_studio", manageUrl: "https://pod-admin.mock-synap.test/apps/app_mock_studio" };
 var MOCK_APP_AGENT_ID = "agent_mock_app";
@@ -153,13 +168,43 @@ function createMockAuthServer(options = {}) {
   const writes = [];
   const proposals = [];
   const seed = options.seed ?? {};
-  const entities = [...seed.entities ?? [], ...options.entities ?? []];
+  const entities = [...seed.entities ?? [], ...options.entities ?? []].map(
+    (e, i) => desugarSeedRoles(e, `entities[${i}]`)
+  );
   const sessions = [...seed.sessions ?? []];
   const documents = [...seed.documents ?? []];
   const relations = [...seed.relations ?? []];
   const templateOf = new Map((seed.spaces ?? []).filter((sp) => sp.templateSlug).map((sp) => [sp.id, sp.templateSlug]));
   const approvals = [];
   const seededAt = new Date(now()).toISOString();
+  const rolesOf = (e) => Array.isArray(e.facets) ? e.facets.filter((f) => typeof f?.slug === "string") : [];
+  function readableEntity(e, spaces, only) {
+    if (typeof e.workspaceId === "string" && kindReadable(e, spaces, e.workspaceId) && (!only || e.workspaceId === only)) return true;
+    return facetsOf(e, spaces, only ?? void 0).some((f) => e.workspaceId == null || !f.sharedRole);
+  }
+  const facetsOf = (e, spaces, lens) => rolesOf(e).filter((f) => typeof f.workspaceId === "string" && kindReadable(e, spaces, f.workspaceId) && (lens === void 0 || f.workspaceId === lens));
+  const facetRow = (f) => ({ facetId: f.facetId, slug: f.slug, properties: f.properties ?? {}, status: f.status ?? null });
+  const entityWire = (e) => {
+    const { facets: _facets, facetSlugs: _facetSlugs, ...wire } = e;
+    return wire;
+  };
+  const readSpaces = (scope) => {
+    const out = /* @__PURE__ */ new Map();
+    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 === void 0 || kind === "*") out.set(g.workspaceId, null);
+      else if (out.get(g.workspaceId) !== null) out.set(g.workspaceId, (out.get(g.workspaceId) ?? /* @__PURE__ */ new Set()).add(kind));
+      else continue;
+    }
+    return out;
+  };
+  const kindReadable = (e, spaces, space) => {
+    if (!spaces.has(space)) return false;
+    const kinds = spaces.get(space);
+    return kinds === null || kinds === void 0 ? kinds === null : kinds.has(String(e.profileSlug ?? e.type ?? ""));
+  };
   for (const p of seed.proposals ?? []) {
     proposals.push({
       proposalType: "create",
@@ -174,7 +219,9 @@ function createMockAuthServer(options = {}) {
       ...p
     });
   }
-  const writeMode = options.writeMode ?? (options.actsAs === "person" ? "applied" : "proposed");
+  let actsAs = options.actsAs;
+  const writeMode = () => options.writeMode ?? (actsAs === "person" ? "applied" : "proposed");
+  let deviceFresh = !options.requireStepUp;
   const graceMs = (options.refreshGraceSec ?? 30) * 1e3;
   const app = options.app === void 0 ? MOCK_APP : options.app;
   let proposalSeq = 0;
@@ -220,7 +267,7 @@ function createMockAuthServer(options = {}) {
       synap_grant: grant.filter((g) => scope.includes(g.permission)).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;
@@ -246,6 +293,21 @@ function createMockAuthServer(options = {}) {
       if (form.resource !== void 0 && row.resource && form.resource !== row.resource) {
         return oauthError("invalid_target", "resource does not match the authorization request");
       }
+      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");
+        }
+        device.used = true;
+        deviceFresh = true;
+        return json(200, tokenBody(row.scope, row.clientId, device.family));
+      }
       for (const r of refreshTokens.values()) if (r.clientId === row.clientId) revokeFamily(r.family);
       return json(200, tokenBody(row.scope, row.clientId, randomToken()));
     }
@@ -307,11 +369,12 @@ function createMockAuthServer(options = {}) {
     triage: { pending: false, acceptedAt: null, acceptedBy: null },
     ...s
   });
-  function readSeeded(path, query) {
+  function readSeeded(path, query, scope) {
+    const spaces = readSpaces(scope);
     const conn = /^\/entities\/([^/]+)\/connections$/.exec(path);
     if (conn) {
       const id = decodeURIComponent(conn[1]);
-      const ws = query.get("workspaceId");
+      const ws = query.get("workspaceId") ?? void 0;
       const limit = Math.min(Math.max(Number(query.get("limit") ?? 50) || 50, 1), 200);
       const inLens = (e) => !ws || e.workspaceId === ws || e.workspaceId == null;
       const connections = [];
@@ -320,10 +383,17 @@ function createMockAuthServer(options = {}) {
         const outgoing = r.sourceEntityId === id;
         const otherId = outgoing ? r.targetEntityId : r.sourceEntityId;
         const other = entities.find((e) => e.id === otherId);
-        if (!other || !inLens(other)) continue;
+        if (!other || !inLens(other) || !readableEntity(other, spaces)) continue;
+        const self = entities.find((e) => e.id === id);
+        if (self && self.workspaceId == null && other.workspaceId == null) continue;
         connections.push({
           entityId: otherId,
-          entity: { ...other, type: other.profileSlug ?? other.type ?? null, facetSlugs: other.facetSlugs ?? [] },
+          // relations.ts: the raw row plus its role slugs under the read's facet lens (a 1.5.0 seed's own facetSlugs otherwise).
+          entity: {
+            ...entityWire(other),
+            type: other.profileSlug ?? other.type ?? null,
+            facetSlugs: rolesOf(other).length > 0 ? facetsOf(other, spaces, ws).map((f) => f.slug) : other.facetSlugs ?? []
+          },
           label: r.type,
           direction: outgoing ? "outgoing" : "incoming",
           source: "graph",
@@ -356,7 +426,39 @@ function createMockAuthServer(options = {}) {
     const entity = /^\/entities\/([^/]+)$/.exec(path);
     if (entity) {
       const found = entities.find((e) => e.id === decodeURIComponent(entity[1]));
-      return found ? json(200, found) : new Response(null, { status: 404 });
+      return found && readableEntity(found, spaces) ? json(200, entityWire(found)) : new Response(null, { status: 404 });
+    }
+    const roles = /^\/entities\/([^/]+)\/facets$/.exec(path);
+    if (roles) {
+      const found = entities.find((e) => e.id === decodeURIComponent(roles[1]));
+      if (!found || !readableEntity(found, spaces)) return new Response(null, { status: 404 });
+      return json(200, {
+        facets: facetsOf(found, spaces).map((f) => ({
+          facet: {
+            id: f.facetId,
+            entityId: found.id,
+            profileId: `profile_${f.slug}`,
+            userId: found.userId ?? user.id,
+            // A stamped facet answers its space; a shared role's facet is stored pod-wide.
+            workspaceId: f.sharedRole ? null : f.workspaceId,
+            contextEntityId: null,
+            status: f.status ?? null,
+            statusCategory: null,
+            properties: f.properties ?? {},
+            metadata: {},
+            createdByKind: null,
+            createdByUserId: null,
+            agentUserId: null,
+            sourceProposalId: null,
+            correlationId: null,
+            createdAt: seededAt,
+            updatedAt: seededAt,
+            deletedAt: null
+          },
+          profile: { id: `profile_${f.slug}`, slug: f.slug, profileKind: "role" },
+          effectiveProperties: []
+        }))
+      });
     }
     const doc = /^\/documents\/([^/]+)$/.exec(path);
     if (doc) {
@@ -412,6 +514,12 @@ function createMockAuthServer(options = {}) {
         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":
@@ -422,12 +530,27 @@ function createMockAuthServer(options = {}) {
     }
     if (method === "GET" && path === "/users/me") return json(200, user);
     if (method === "GET" && path === "/entities") {
-      const ws = query.get("workspaceId");
+      const ws = query.get("workspaceId") || void 0;
       const kind = query.get("profileSlug");
+      const role = query.get("facetSlug");
+      const podWide = query.get("includePodWide") !== "false";
+      const withFacets = query.get("includeFacets") === "true";
       const offset = Number(query.get("offset") ?? 0) || 0;
       const limit = Number(query.get("limit") ?? 50) || 50;
-      const rows = entities.filter((e) => (!ws || e.workspaceId === ws) && (!kind || e.profileSlug === kind));
-      return json(200, rows.slice(offset, offset + limit));
+      const spaces = readSpaces(row.scope);
+      const rows = entities.filter((e) => {
+        if (!readableEntity(e, spaces, ws)) return false;
+        if (ws && !podWide && e.workspaceId !== ws && !facetsOf(e, spaces, ws).some((f) => !f.sharedRole)) return false;
+        const slugs = facetsOf(e, spaces, ws).map((f) => f.slug);
+        return (!kind || e.profileSlug === kind || slugs.includes(kind)) && (!role || slugs.includes(role));
+      });
+      return json(
+        200,
+        rows.slice(offset, offset + limit).map((e) => {
+          const facets = withFacets ? facetsOf(e, spaces, ws).map(facetRow) : [];
+          return facets.length > 0 ? { ...entityWire(e), facetSlugs: facets.map((f) => f.slug), facets } : entityWire(e);
+        })
+      );
     }
     if (method === "GET" && path === "/proposals") {
       const readable = new Set(grant.filter((g) => g.permission === "proposal.read" && row.scope.includes(g.permission)).map((g) => g.workspaceId));
@@ -442,14 +565,15 @@ function createMockAuthServer(options = {}) {
       return json(200, { proposals: page, limit, offset, total: rows.length, hasMore: offset + page.length < rows.length });
     }
     if (method === "GET") {
-      const read = readSeeded(path, query);
+      const read = readSeeded(path, query, row.scope);
       if (read) return read;
     }
     const approve = method === "POST" ? /^\/proposals\/([^/]+)\/approve$/.exec(path) : null;
     if (approve) {
-      if (options.actsAs !== "person") {
+      if (actsAs !== "person") {
         return json(403, { error: "An agent credential cannot approve proposals \u2014 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" });
       if (!grant.some((g) => g.permission === "proposal.approve" && row.scope.includes(g.permission) && g.workspaceId === p.workspaceId)) {
@@ -460,11 +584,26 @@ function createMockAuthServer(options = {}) {
       approvals.push(p.id);
       return json(200, { success: true, proposalId: p.id, proposal: { ...p } });
     }
+    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" });
+    }
+    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 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 : {};
       const workspaceId = typeof fields.workspaceId === "string" ? fields.workspaceId : null;
-      if (writeMode === "proposed") {
+      if (writeMode() === "proposed") {
         const proposalId = `prop_mock_${++proposalSeq}`;
         proposals.push({
           id: proposalId,
@@ -581,9 +720,15 @@ function createMockAuthServer(options = {}) {
       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 ?? void 0;
+    },
+    expireStepUp() {
+      deviceFresh = false;
+    },
     consumeRefreshToken(t) {
       const row = refreshTokens.get(t);
       if (row) row.used = true;
@@ -637,9 +782,36 @@ function parseMockPodSeed(input) {
       for (const field of REQUIRED[key]) {
         if (typeof row[field] !== "string") throw new TypeError(`seed.${key}[${i}].${field}: expected a string`);
       }
+      if (key === "entities") checkFacets(row.facets, `seed.entities[${i}].facets`);
     });
   }
-  return JSON.parse(JSON.stringify(obj));
+  obj.entities?.forEach((row, i) => {
+    const roles = row.seedRoles;
+    if (roles === void 0) return;
+    if (!Array.isArray(roles)) throw new TypeError(`seed.entities[${i}].seedRoles: expected an array`);
+    roles.forEach((r, j) => {
+      for (const field of ["profileSlug", "workspaceId"]) {
+        if (!r || typeof r !== "object" || typeof r[field] !== "string") {
+          throw new TypeError(`seed.entities[${i}].seedRoles[${j}].${field}: expected a string`);
+        }
+      }
+    });
+  });
+  const out = JSON.parse(JSON.stringify(obj));
+  if (out.entities) out.entities = out.entities.map((row, i) => desugarSeedRoles(row, `seed.entities[${i}]`));
+  return out;
+}
+function checkFacets(facets, at) {
+  if (facets === void 0) return;
+  if (!Array.isArray(facets)) throw new TypeError(`${at}: expected an array`);
+  facets.forEach((f, j) => {
+    if (!f || typeof f !== "object" || Array.isArray(f)) throw new TypeError(`${at}[${j}]: expected an object`);
+    for (const field of ["facetId", "slug", "workspaceId"]) {
+      if (typeof f[field] !== "string") throw new TypeError(`${at}[${j}].${field}: expected a string`);
+    }
+    const shared = f.sharedRole;
+    if (shared !== void 0 && typeof shared !== "boolean") throw new TypeError(`${at}[${j}].sharedRole: expected a boolean`);
+  });
 }
 
 // src/testing/cloud.ts