@spacefast/common 0.0.12 → 0.0.17

package/dist/contracts/access.js

@@ -1,1091 +1,360 @@
 import { z } from "zod";
-import { ISO_COUNTRY_CODES } from "./countries.js";
-// Unified access contracts (internal-docs/access-plan.html — the only access
-// document).
-//
-// The one access & policy lane. The headline simplification: **firewall ⊂
-// access** — there is exactly one Rule schema, and an anonymous firewall rule
-// is simply a Rule whose `auth` is absent. There is exactly ONE satisfaction
-// test: token grants ∩ requiredGrants (X-32); `auth.acquire` only configures
-// how the challenge page lets a visitor obtain a token. The runtime verifies
-// fully offline; the cloud resolves identity and mints signed tokens (plus
-// exactly one non-cloud minter: the runtime's space-local `pw:` mint). Field
-// names are the spec contract — do not rename.
+import { grantConstraintsPatchSchema, grantConstraintsSchema, grantResourceSetSchema, grantTargetSelectorSchema, } from "./grants.js";
 // ---------------------------------------------------------------------------
-// 1. Grants
+// Canonical sharing model
 // ---------------------------------------------------------------------------
-// A grant is a string in a verified token (or a `requiredGrants` entry on a
-// rule). Identity is a string set: the runtime is a verifier and
-// set-intersector — a visitor passes when `grants ∩ requiredGrants ≠ ∅`.
-//
-// Grants are globs. One namespace per kind, with `*` wildcards permitted in
-// `requiredGrants` so a rule can name a class of identities:
-//
-//   email:alice@acme.com        a single verified email
-//   email:*@acme.com            any verified email on a domain (glob — this IS
-//                               the "anyone at a domain" audience; there is no
-//                               separate email-domain namespace)
-//   team:team_123:member        top-level team membership at a role
-//   sub-team:sub_123:member     enterprise group membership inside a team
-//   user:<handle>               a specific platform person
-//   space:{spaceId}:{level}     a leveled space grant (SPACE_LEVELS)
-//   link:lnk_x                  an active share link (structural revocation)
-//   invite:sin_x                an accepted invite (structural revocation)
-//   svc:stk_x                   a service token (CI, agents; structural)
-//   sso:acn_x                   an OIDC connection identity
-//   ext:{connectionId}:<tag>    an owner-defined external (BYO issuer) grant
-//   pw:{ruleId}                 a satisfied password wall (runtime-local mint —
-//                               the ONLY namespace the space-local key signs)
-//
-// Namespaces exist iff a minter exists. Tokens signed by an external (BYO) key
-// may only carry grants namespaced to that key (see
-// `accessKeySchema.grantNamespaces`); everything else is dropped before
-// intersection.
-export const grantSchema = z.string().min(1).max(255);
-// Known grant namespace prefixes — final vocabulary (access-plan §1).
-export const GRANT_NAMESPACES = [
-    "email:",
-    "team:",
-    "sub-team:",
-    "user:",
-    "space:",
-    "link:",
-    "invite:",
-    "svc:",
-    "sso:",
-    "ext:",
-    "pw:",
-];
-const GRANT_PATTERN = /^(email|team|sub-team|user|space|link|invite|svc|sso|ext|pw):.+$/;
-// Validator for grant globs like "email:*@acme.com", "team:team_123:member",
-// "sub-team:sub_123:member", "user:<h>", "svc:…", "ext:{conn}:…". Returns true when the grant string is a
-// well-formed `namespace:value`. This is advisory (the runtime intersects
-// opaque strings); use it for authoring-surface validation, not enforcement.
-export function isWellFormedGrant(grant) {
-    return GRANT_PATTERN.test(grant);
+export const SPACE_ACCESS_PRESETS = ["private", "team", "public"];
+export const ACCESS_HANDOFF_MEDIA_TYPE = "application/vnd.spacefast.access-handoff+json";
+export const spaceAccessPresetSchema = z.enum(SPACE_ACCESS_PRESETS);
+export const ACCESS_ROLES = ["viewer", "commenter", "editor", "manager"];
+export const accessRoleSchema = z.enum(ACCESS_ROLES);
+export function accessRoleRank(role) {
+    return ACCESS_ROLES.indexOf(role);
 }
-// A `requiredGrants` entry may contain `*` wildcards; a minted token grant must
-// be concrete (no `*`). Both share `grantSchema`; this narrows the authoring
-// case.
-export const requiredGrantSchema = grantSchema.refine(isWellFormedGrant, {
-    message: "grant must be namespaced, e.g. email:*@acme.com, team:team_123:member, sub-team:sub_123:member, user:<h>, svc:…, ext:{conn}:…",
-});
-// The ONE space-level vocabulary (access-plan X-38): consumed by
-// `space:{id}:{level}` grants, Cast's capability table, invitee levels, and the
-// future editor role. No parallel level enum may exist anywhere. v1 surfaces
-// mint only `viewer` and `commenter`.
-export const SPACE_LEVELS = ["viewer", "commenter", "editor", "admin"];
-export const spaceLevelSchema = z.enum(SPACE_LEVELS);
-// ---------------------------------------------------------------------------
-// 2. Issuer registry
-// ---------------------------------------------------------------------------
-// A registered signing key. SSO + BYO-issuer keys are registered once at
-// team/space level; rules reference grants, and a token's grants are dropped
-// unless namespaced to one of `grantNamespaces`. Service tokens are just tokens
-// carrying `svc:` grants signed by a platform key.
-export const accessKeySchema = z.object({
-    kid: z.string().min(1).describe("Key id; matches the token header `kid`."),
-    alg: z.literal("EdDSA"),
-    publicKey: z.string().min(1).describe("base64url-encoded raw Ed25519 public key."),
-    // Grants in a token signed by this key are DROPPED unless prefixed by one of
-    // these. Platform keys list the platform prefixes
-    // (["team:","sub-team:","user:","email:","space:","link:","svc:","sso:"]);
-    // external keys list exactly ["ext:{connectionId}:"], bounding a leaked key's
-    // blast radius to the rules the owner pointed at it.
-    grantNamespaces: z.array(z.string().min(1)).min(1),
-});
-// ---------------------------------------------------------------------------
-// 2b. Identity connections (access-plan §4.4/§6.2/§6.3, X-18/X-19)
-// ---------------------------------------------------------------------------
-// A team-level identity connection (`acn_` row): either a company OIDC
-// relying-party config (§6.2 — the authorize endpoint runs the code flow and
-// mints the visitor token; no Spacefast account is created) or an external
-// BYO issuer (§6.3 — the shop holds the private key and mints its own
-// Ed25519 tokens; Spacefast is not in the login path).
-export const ACCESS_CONNECTION_TYPES = ["oidc", "external"];
-export const accessConnectionTypeSchema = z.enum(ACCESS_CONNECTION_TYPES);
-// Session TTL defaults (§4.4): 8h for company SSO (re-auth is a transparent
-// bounce while the IdP session lives), 30min for external issuers (the short
-// TTL bounds entitlement drift — a cancelled subscriber survives at most one
-// TTL).
-export const OIDC_CONNECTION_DEFAULT_TTL_SECONDS = 8 * 60 * 60; // 28800
-export const EXTERNAL_CONNECTION_DEFAULT_TTL_SECONDS = 30 * 60; // 1800
-// Hard ceiling on an EXTERNAL-issued token's exp (§6.3: exp ≤ 30min). The
-// connection's sessionTtlSeconds may be shorter, never longer.
-export const EXTERNAL_TOKEN_MAX_TTL_SECONDS = 30 * 60;
-// The grant a company-SSO visitor carries (§6.2): `sso:{connectionId}`.
-export function ssoGrant(connectionId) {
-    return `sso:${connectionId}`;
-}
-// The grant namespace an external connection's keys are bound to (§6.3):
-// tokens signed by a shop key are dropped unless prefixed `ext:{acn}:` — a
-// leaked shop key can forge exactly the rules the owner pointed at it, never
-// team:/user: grants (corpus-pinned).
-export function externalGrantNamespace(connectionId) {
-    return `ext:${connectionId}:`;
-}
-// An owner-defined external grant (§6.3): `ext:{acn}:{tag}`, e.g.
-// `ext:acn_x:wc-subscriber`.
-export function externalGrant(connectionId, tag) {
-    return `ext:${connectionId}:${tag}`;
-}
-// STORED form of a connection login acquire (`loginAcquireSchema.url`): the
-// compiler stores the symbolic `connection:{acn}` reference and the resolver
-// rewrites it to the live URL on every policy resolution (the OIDC leg URL or
-// the shop's authorizeUrl with the CURRENT space/sv baked in). The serving
-// runtime adds the actual request host and same-origin return path. Nothing
-// stored ever carries a stale sessionVersion; a revoked connection's acquire
-// resolves to nothing (the login block disappears — fail closed).
-export function connectionAcquireRef(connectionId) {
-    return `connection:${connectionId}`;
+export function maxAccessRole(left, right) {
+    if (left === null)
+        return right;
+    if (right === null)
+        return left;
+    return accessRoleRank(left) >= accessRoleRank(right) ? left : right;
 }
-export function parseConnectionAcquireRef(url) {
-    if (!url.startsWith("connection:")) {
-        return null;
+function hasUnsafeScopeCharacter(value) {
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint === undefined ||
+            codePoint <= 0x1f ||
+            codePoint === 0x7f ||
+            character === "\\" ||
+            character === "?" ||
+            character === "#") {
+            return true;
+        }
     }
-    const id = url.slice("connection:".length);
-    return id.length > 0 && !id.includes("/") && !id.includes(":") ? id : null;
+    return false;
 }
-// The connection ids a rule references — through `sso:{acn}` / `ext:{acn}:…`
-// requiredGrants or symbolic `connection:{acn}` acquire refs. The resolver
-// embeds these connections' keys/acquire legs at hydration time.
-export function referencedConnectionIds(input) {
-    const ids = new Set();
-    for (const grant of input.requiredGrants ?? []) {
-        if (grant.startsWith("sso:")) {
-            const id = grant.slice("sso:".length);
-            if (id && !id.includes(":")) {
-                ids.add(id);
-            }
-        }
-        else if (grant.startsWith("ext:")) {
-            const id = grant.slice("ext:".length).split(":")[0];
-            if (id) {
-                ids.add(id);
-            }
-        }
+/**
+ * Canonicalizes the URL route identity used by People, Links, requests,
+ * comments, and runtime authorization.
+ */
+export function normalizeAccessScopePath(input) {
+    const value = input;
+    if (!value.startsWith("/") || value.startsWith("//") || hasUnsafeScopeCharacter(value)) {
+        throw new TypeError("scope must be a plain absolute URL path");
+    }
+    let decoded;
+    try {
+        decoded = decodeURIComponent(value);
+    }
+    catch {
+        throw new TypeError("scope contains malformed percent encoding");
     }
-    for (const acquire of input.acquire ?? []) {
-        if (acquire.type === "login" && acquire.url) {
-            const id = parseConnectionAcquireRef(acquire.url);
-            if (id) {
-                ids.add(id);
+    if (/%2f|%5c/iu.test(value) || hasUnsafeScopeCharacter(decoded)) {
+        throw new TypeError("scope contains an ambiguous encoded separator");
+    }
+    const segments = [];
+    for (const rawSegment of decoded.split("/")) {
+        const segment = rawSegment.normalize("NFC");
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..") {
+            if (segments.length === 0) {
+                throw new TypeError("scope escapes the URL root");
             }
+            segments.pop();
+            continue;
         }
+        segments.push(segment);
+    }
+    if (segments.at(-1) === "index.html") {
+        segments.pop();
     }
-    return [...ids];
+    return segments.length === 0 ? "/" : `/${segments.join("/")}`;
 }
-// A raw Ed25519 public key is 32 bytes → 43 base64url chars, no padding.
-export const externalConnectionPublicKeySchema = z.object({
-    kid: z.string().min(1).max(64),
-    publicKey: z
-        .string()
-        .regex(/^[A-Za-z0-9_-]{43}$/, "publicKey must be a base64url raw 32-byte Ed25519 public key"),
-});
-const guestEmailDomainsSchema = z
-    .array(z
+export const accessScopePathSchema = z
     .string()
-    .min(3)
-    .max(255)
-    .regex(/^[a-z0-9.-]+\.[a-z]{2,}$/i, "must be a bare domain, e.g. acme.com"))
-    .max(20);
-// The connection projected onto the wire — the OIDC client secret NEVER
-// appears (masked after write, §4.4); `clientSecretSet` says one is stored.
-export const accessConnectionSchema = z.object({
-    id: z.string().min(1),
-    teamId: z.string().min(1),
-    type: accessConnectionTypeSchema,
-    name: z.string().min(1),
-    // OIDC half (null for external connections).
-    issuer: z.string().min(1).nullable().default(null),
-    clientId: z.string().min(1).nullable().default(null),
-    clientSecretSet: z.boolean().default(false),
-    // External half (null for oidc connections). `authorizeUrl` is HTTPS-pinned
-    // at create and admin-only to mutate.
-    authorizeUrl: z.string().min(1).nullable().default(null),
-    publicKeys: z.array(externalConnectionPublicKeySchema).default([]),
-    sessionTtlSeconds: z.number().int().positive(),
-    // Verified-email domains auto-granted team-viewer at mint (§6.2); null = none.
-    guestEmailDomains: z.array(z.string().min(1)).nullable().default(null),
-    createdAt: z.string().min(1),
-    revokedAt: z.string().min(1).nullable().default(null),
-    active: z.boolean(),
-});
-export const oidcConnectionCreateSchema = z.object({
-    type: z.literal("oidc"),
-    name: z.string().min(1).max(200),
-    // The IdP issuer URL (HTTPS): discovery runs against
-    // `{issuer}/.well-known/openid-configuration`.
-    issuer: z.string().min(1).max(1024),
-    clientId: z.string().min(1).max(512),
-    clientSecret: z.string().min(1).max(2048),
-    sessionTtlSeconds: z
-        .number()
-        .int()
-        .min(60)
-        .max(24 * 60 * 60)
-        .optional(),
-    guestEmailDomains: guestEmailDomainsSchema.optional(),
-});
-export const externalConnectionCreateSchema = z.object({
-    type: z.literal("external"),
-    name: z.string().min(1).max(200),
-    // The shop's authorize endpoint (HTTPS-pinned): the challenge page's login
-    // link forwards straight here for single-audience external rules.
-    authorizeUrl: z.string().min(1).max(2048),
-    publicKeys: z.array(externalConnectionPublicKeySchema).min(1).max(5),
-    sessionTtlSeconds: z.number().int().min(60).max(EXTERNAL_TOKEN_MAX_TTL_SECONDS).optional(),
-    guestEmailDomains: guestEmailDomainsSchema.optional(),
-});
-export const accessConnectionCreateSchema = z.discriminatedUnion("type", [
-    oidcConnectionCreateSchema,
-    externalConnectionCreateSchema,
-]);
-// PATCH shape — fields are validated against the connection's type at the
-// route (`authorizeUrl`/`publicKeys` are external-only; `issuer`/`clientId`/
-// `clientSecret` are oidc-only). `publicKeys` REPLACES the key set (push-key
-// rotation: push the new key alongside the old, flip signing, drop the old).
-export const accessConnectionUpdateSchema = z.object({
-    name: z.string().min(1).max(200).optional(),
-    issuer: z.string().min(1).max(1024).optional(),
-    clientId: z.string().min(1).max(512).optional(),
-    clientSecret: z.string().min(1).max(2048).optional(),
-    authorizeUrl: z.string().min(1).max(2048).optional(),
-    publicKeys: z.array(externalConnectionPublicKeySchema).min(1).max(5).optional(),
-    sessionTtlSeconds: z
-        .number()
-        .int()
-        .min(60)
-        .max(24 * 60 * 60)
-        .optional(),
-    guestEmailDomains: guestEmailDomainsSchema.nullable().optional(),
-});
-// DELETE response: revocation is structural — rules referencing the
-// connection lose those grants in the immediate recompile; rules left with an
-// empty audience are disabled (removed) and listed so the owner knows exactly
-// what stopped enforcing via that connection.
-export const accessConnectionRevokeResultSchema = z.object({
-    connection: accessConnectionSchema,
-    disabledRules: z
-        .array(z.object({ spaceId: z.string().min(1), ruleId: z.string().min(1) }))
-        .default([]),
-});
-// ---------------------------------------------------------------------------
-// 3. The unified runtime Rule (firewall = a rule with no auth)
-// ---------------------------------------------------------------------------
-// The `auth` object (access-plan X-32): there is exactly ONE satisfaction
-// test — token grants ∩ `requiredGrants`. `acquire` entries only configure how
-// the challenge page lets an unsatisfied visitor OBTAIN a token:
-//
-//   password → the challenge page renders a password form; a valid POST mints
-//              the standard visitor token RUNTIME-LOCALLY (space HS256 key,
-//              `pw:{ruleId}` grant) into the one `spacefast_access` cookie.
-//              `basic` transport is the stateless HTTP 401 variant — valid
-//              Basic credentials satisfy `pw:{ruleId}` per-request (browsers
-//              replay the Authorization header; no cookie needed).
-//   login    → the challenge page renders a sign-in link into the cloud
-//              authorize chain (or a BYO issuer's authorizeUrl).
-//
-// Mixed audiences are just multiple acquire entries on one rule — the chooser
-// is the challenge page rendering every acquire block, never a new surface.
-export const passwordAcquireSchema = z.object({
-    type: z.literal("password"),
-    // A secret reference (e.g. "secret:space-password"), never plaintext. The
-    // runtime resolves it from serving secrets and `password_verify`s.
-    ref: z.string().min(1),
-    transport: z.enum(["basic", "form"]),
-    username: z.string().min(1).optional(),
-});
-export const loginAcquireSchema = z.object({
-    type: z.literal("login"),
-    // Interactive handoff target (the cloud authorize endpoint, or a BYO
-    // connection's authorizeUrl). The challenge page links only to the runtime's
-    // same-origin login endpoint; it never exposes this target directly. The
-    // compiler hydrates static identity intent, then the runtime sets `host=`
-    // from the actual serving request and `return=` as a plain same-origin path.
-    url: z.string().min(1),
-    // Display label for the challenge-page button (e.g. "Continue with
-    // Spacefast", "Sign in with Acme Shop").
-    label: z.string().min(1).optional(),
-});
-export const acquireSchema = z.discriminatedUnion("type", [
-    passwordAcquireSchema,
-    loginAcquireSchema,
-]);
-export const ruleAuthSchema = z.object({
-    // ANY-OF: the visitor's verified grants must intersect this set. Entries may
-    // be globs (e.g. "email:*@acme.com").
-    requiredGrants: z.array(grantSchema).min(1),
-    // Issuer keys whose tokens are accepted for this rule. When omitted, the
-    // compiler fills in the applicable platform/registered keys. Tokens signed by
-    // a key contribute only grants within that key's `grantNamespaces`.
-    issuers: z.array(accessKeySchema).optional(),
-    // How the challenge page lets a visitor get a token. Absent = no interactive
-    // acquisition (service-token-only rule): the runtime denies a browser rather
-    // than loop.
-    acquire: z.array(acquireSchema).optional(),
-});
-// Match conditions AND together (host AND path AND channel AND ipCidrs AND …).
-// All fields optional; an empty match matches everything in scope.
-export const ruleMatchSchema = z.object({
-    host: z.string().min(1).optional(),
-    hostPattern: z.string().min(1).optional(),
-    // `_headers` absolute host matcher template: ":branch.example.com" keeps
-    // placeholders single-label while "*" keeps the existing host wildcard shape.
-    hostTemplate: z.string().min(1).optional(),
-    // Glob path pattern: "/docs/**" | "/docs/*" | "/x.html".
-    pathPattern: z.string().min(1).optional(),
-    // Serving context channel name (e.g. "live", "staging").
-    channel: z.string().min(1).optional(),
-    // CIDR v4/v6 list; the request IP must fall in one of these.
-    ipCidrs: z.array(z.string().min(1)).max(50).optional(),
-    // User-agent matcher (e.g. block a crawler, gate an agent).
-    agent: z.string().min(1).optional(),
-    // ISO 3166-1 alpha-2 country code matcher.
-    country: z.string().min(2).max(2).optional(),
-    // Matches when the resolved country is NOT in this list. Unlike compiling
-    // an allowlist as the finite ISO complement, this also matches missing,
-    // provider-special, malformed, and future country values.
-    countryNotIn: z.array(z.string().min(2).max(2)).min(1).max(250).optional(),
-    // Single request-header matcher: name + expected value.
-    header: z.object({ name: z.string().min(1), value: z.string() }).optional(),
-});
-// Managed-block owners (access-plan X-34). Block ownership is THIS schema
-// field, never a reasonCode convention: `managedBy` is stripped/rejected from
-// all user input, so a raw rule can never claim or clobber a managed block.
-// Cloud-lane block order: operator/incident rules first, then `firewall`, then
-// `sharing`/`file_share`/`cast_reviewer`, then `team_default` last.
-export const MANAGED_BY_VALUES = [
-    "sharing",
-    "firewall",
-    "file_share",
-    "cast_reviewer",
-    "team_default",
-];
-export const managedBySchema = z.enum(MANAGED_BY_VALUES);
-// The one Rule. `match` (AND) selects requests; `effect` is what happens on
-// match; `auth` (absent = anonymous firewall) gates `challenge`/`allow`.
-export const runtimeRuleSchema = z.object({
-    // Stable rule id. Required wherever a grant references the rule
-    // (`pw:{ruleId}`); the compiler assigns ids to managed rules.
-    id: z.string().min(1).optional(),
-    match: ruleMatchSchema.default({}),
-    effect: z.enum(["allow", "deny", "challenge"]),
-    // Absent = anonymous firewall rule (no credential required). Present = pass
-    // when token grants ∩ requiredGrants ≠ ∅ (the one satisfaction test).
-    auth: ruleAuthSchema.optional(),
-    // Which product surface owns this rule (managed blocks). Never accepted from
-    // user input — `replaceManagedRules` is the only writer.
-    managedBy: managedBySchema.optional(),
-    // Unix seconds. TTL'd interventions (`sf block --ttl`): the runtime SKIPS an
-    // expired rule at match time (one timestamp compare, no recompile needed);
-    // the compiler GCs expired rules on the next write.
-    expiresAt: z.number().int().nonnegative().optional(),
-    // Surfaced on a `deny` (X-Spacefast-Reason header) and the rendered platform
-    // page so an operator/visitor can tell which rule fired and why. Diagnostic
-    // only — never load-bearing for ownership or semantics.
-    reasonCode: z.string().min(1).optional(),
-    message: z.string().min(1).optional(),
-});
-// ---------------------------------------------------------------------------
-// 3b. Visitor token (the cloud "mint" half)
-// ---------------------------------------------------------------------------
-// The header `kid`/`alg` the platform signs visitor tokens with. These match
-// the runtime JWKS key (`spacefast-runtime-v1` / EdDSA) so the runtime's
-// JWKS-by-kid verify (shared/jwt.php) accepts a token the cloud minted. Do
-// NOT introduce a second key system — these constants name the existing one.
-export const ACCESS_TOKEN_KID = "spacefast-runtime-v1";
-export const ACCESS_TOKEN_ALG = "EdDSA";
-// The published JWKS path (served under /.well-known/ by the control plane and
-// fetched by the runtime + Cast).
-export const RUNTIME_JWKS_WELL_KNOWN_FILENAME = "spacefast-runtime-jwks.json";
-// The `kid` the runtime's SPACE-LOCAL HS256 mint signs under (access-plan
-// §3.1). The key derives from the space's password secret + sessionVersion and
-// may only sign `pw:` grants — the same namespace filter that bounds BYO keys
-// bounds this one. Never published in any JWKS; verification re-derives the
-// key from serving secrets.
-export const LOCAL_PW_TOKEN_KID = "spacefast-local-pw-v1";
-// The claim set carried by a minted visitor token. `grants` are concrete
-// (no `*`), `email:`/`user:`/`team:<teamId>:<role>`/`sub-team:<subTeamId>:<role>` namespaced so they survive
-// the platform issuer's `grantNamespaces` filter at the runtime. `aud`, when
-// present, lowercases-binds the token to a single serving host.
-export const accessTokenPayloadSchema = z.object({
-    // Subject: the authenticated platform user id the token was minted for
-    // (or "invite:sin_x" / "link:lnk_x" / "pw:anon" for account-less audiences).
-    sub: z.string().min(1),
-    // Concrete (non-glob) grants. The runtime intersects these with a rule's
-    // `requiredGrants`; the visitor passes when the intersection is non-empty.
-    grants: z.array(grantSchema).default([]),
-    // Unix seconds. Mirrors the runtime's exp check (300s leeway).
-    exp: z.number().int().nonnegative(),
-    nbf: z.number().int().nonnegative().optional(),
-    iat: z.number().int().nonnegative().optional(),
-    iss: z.string().min(1).optional(),
-    // Optional host binding (lowercased) — when set the token is only accepted on
-    // that serving host.
-    aud: z.string().min(1).optional(),
-    // Space session version (access-plan §3.1): the runtime rejects a visitor
-    // token whose `sv` mismatches `policy.sessionVersion`. Logout-all is an `sv`
-    // bump — structural, TTL-independent revocation. Absent = 0.
-    sv: z.number().int().nonnegative().optional(),
-    // Single-use id for authorize-chain callback handoffs (access-plan X-29):
-    // the runtime callback consumes `jti` in its replay cache, so a token lifted
-    // from browser history is dead after first use. Share tokens carry no `jti`
-    // (the share URL IS the credential; revocation is structural).
-    jti: z.string().min(1).optional(),
-    // Cast room capability. Collaboration tokens are valid for exactly one
-    // canonical room; other visitor tokens omit it.
-    room: z.string().min(1).optional(),
-    // Anonymous Comments tokens remain anonymous identities even though they
-    // carry a signed room capability.
-    anonymous_id: z.string().min(1).optional(),
-    name: z.string().min(1).max(120).optional(),
-});
-// Authorize request for `POST /v1/spaces/:id/access/authorize` — surviving for
-// exactly one caller: the dashboard preview-token mint (iframe → runtime
-// callback). It never sets cookies; only the runtime callback sets the visitor
-// cookie. `aud` binds the token to the previewed host.
-export const authorizeRequestSchema = z.object({
-    aud: z.string().min(1).optional(),
-});
-// Authorize response: the signed compact JWT plus its decoded claims (so a
-// caller can show/inspect the grants without re-parsing).
-export const authorizeResponseSchema = z.object({
-    // The signed compact EdDSA JWT (`header.claims.signature`, base64url).
-    token: z.string().min(1),
-    // Decoded claims of `token` (echo of what was signed).
-    payload: accessTokenPayloadSchema,
-    // Unix seconds the token expires at (convenience mirror of `payload.exp`).
-    expiresAt: z.number().int().nonnegative(),
-});
-// ---------------------------------------------------------------------------
-// 3b'. Access events (access-plan §5.6b, X-37)
-// ---------------------------------------------------------------------------
-// The access event is a first-class contract from day one: the runtime emits
-// one per enforced decision into the per-hostname analytics ingestion; the
-// Views panel is a reader of an already-flowing stream. `grantsHash` is a
-// sha256 of the sorted verified grant list (never the grants themselves).
-export const accessEventSchema = z.object({
-    sub: z.string().min(1).nullable().default(null),
-    grantsHash: z.string().min(1).nullable().default(null),
-    ruleId: z.string().min(1).nullable().default(null),
-    effect: z.enum(["allow", "deny", "challenge"]),
-    reasonCode: z.string().min(1).nullable().default(null),
-    host: z.string().min(1),
-    path: z.string().min(1),
-    // Unix seconds.
-    ts: z.number().int().nonnegative(),
+    .min(1)
+    .max(1024)
+    .check((context) => {
+    try {
+        context.value = normalizeAccessScopePath(context.value);
+    }
+    catch (error) {
+        context.issues.push({
+            code: "custom",
+            input: context.value,
+            message: error instanceof Error ? error.message : "invalid access scope",
+        });
+    }
 });
-// ---------------------------------------------------------------------------
-// 3c. Mint-time grant builders (the cloud "resolve identity → grants" half)
-// ---------------------------------------------------------------------------
-// The leveled space grant (access-plan X-38): `space:{spaceId}:{level}` where
-// level ∈ SPACE_LEVELS. The `space:` namespace is on the platform issuer, so
-// the runtime keeps it; Cast keys its capability table off this grant; the
-// accepted-invite path mints the `viewer` level.
-export function spaceLevelGrant(spaceId, level) {
-    return `space:${spaceId}:${level}`;
+export function accessScopeContains(scope, path) {
+    const canonicalScope = normalizeAccessScopePath(scope);
+    const canonicalPath = normalizeAccessScopePath(path);
+    return (canonicalScope === "/" ||
+        canonicalPath === canonicalScope ||
+        canonicalPath.startsWith(`${canonicalScope}/`));
 }
-// The concrete grant a share-link holder carries: a token with `link:{linkId}`
-// intersects the `sharing:`-block rule whose `requiredGrants` the compiler
-// fills from the ACTIVE link rows (§5.2). Revoking the link recompiles it out
-// and the token goes inert. The platform issuer lists the `link:` namespace.
-export function shareLinkGrant(linkId) {
-    return `link:${linkId}`;
+export const authorityReferenceSchema = z
+    .string()
+    .regex(/^(member|person|link|password|machine|claim-preview|external):[A-Za-z0-9_.-]+$/);
+// WHO a session is, orthogonal to WHAT it may do. A session has exactly one
+// principal and any number of authorities; neither implies the other. A member
+// who arrives by share link is still that member, and a link authority alone
+// never makes someone anonymous.
+export const accountPrincipalSchema = z.string().regex(/^account:[A-Za-z0-9_-]+$/);
+// The three kinds of somebody. `account:` is a Spacefast user. `person:` is
+// someone this Space invited by email and who accepted — a real, named identity
+// with no platform account behind it. `external:` is a subject an identity
+// connection vouched for. Anything else — a share Link, a password, a machine
+// key, a claim preview — authenticates no one: those sessions stay anonymous
+// and carry the credential purely as an authority.
+export const identifiedPrincipalSchema = z
+    .string()
+    .regex(/^(?:account|person|external):[A-Za-z0-9_.-]+$/);
+export const accessPrincipalSchema = z.union([z.literal("anonymous"), identifiedPrincipalSchema]);
+export function accountPrincipal(userId) {
+    return accountPrincipalSchema.parse(`account:${userId}`);
 }
-// The concrete grant an invited viewer carries: `invite:{inviteId}` compiled
-// per active invite (§5.3); revocation is structural.
-export function inviteGrant(inviteId) {
-    return `invite:${inviteId}`;
+/** The user id behind an account principal; null for anonymous or malformed. */
+export function accountPrincipalUserId(principal) {
+    if (!principal || !accountPrincipalSchema.safeParse(principal).success)
+        return null;
+    return principal.slice("account:".length);
 }
-// The concrete grant a service token carries: `svc:{tokenId}` compiled
-// wherever the token's `actsAs` satisfies (§5.5); revocation is structural.
-export function serviceTokenGrant(tokenId) {
-    return `svc:${tokenId}`;
+/**
+ * The identity an authority reference names on its own, if any. Credential
+ * classes name nobody. This is the ONE place a class maps to an identity: at
+ * the exchange that just authenticated it, never downstream.
+ */
+export function principalForAuthority(reference) {
+    return reference.startsWith("person:") || reference.startsWith("external:")
+        ? identifiedPrincipalSchema.parse(reference)
+        : undefined;
 }
-// ---------------------------------------------------------------------------
-// 3d. Share links + the sharing projection (access-plan §5.1/§5.2, X-33)
-// ---------------------------------------------------------------------------
-// Share tokens are re-signed on demand from the link row (§5.2): the JWT is
-// never stored, only the row. Credential lifetime = artifact lifetime: `exp`
-// IS the link's expiry and is omitted for a never-expiring link. The runtime
-// permits that omission only for a signed, audience-bound token whose subject
-// and sole grant are the same `link:` capability. Revocation remains
-// structural — the grant drops from the compiled rules.
-// A share link row projected onto the wire (§4.4). `path` is "/" for a
-// space-wide link; any other value scopes the link's grant to that subtree
-// (compile-time: the grant only ever appears in rules matching the path).
-// `lastUsedAt`/`useCount` are the operational-observability columns (X-28);
-// the runtime-side `?sf_share=` trade increments them offline, so they read 0
-// until that ingestion lands.
-export const shareLinkSchema = z.object({
+export const personGrantSchema = z.object({
     id: z.string().min(1),
-    spaceId: z.string().min(1),
-    label: z.string().min(1).nullable().default(null),
-    path: z.string().min(1),
-    createdBy: z.string().min(1).nullable().default(null),
-    // Unix seconds; null = the link never expires. The minted token mirrors this
-    // by omitting exp — there is no hidden shorter fuse.
-    expiresAt: z.number().int().nonnegative().nullable().default(null),
-    createdAt: z.string().min(1).describe("ISO 8601 timestamp."),
-    lastUsedAt: z.string().min(1).nullable().default(null),
-    useCount: z.number().int().nonnegative().default(0),
-    // false once revoked or past expiry — the grant is no longer compiled.
-    active: z.boolean(),
-});
-export const shareLinkCreateSchema = z.object({
-    // A plain absolute path ("/" = the whole space).
-    path: z.string().min(1).max(1024).default("/"),
-    // Unix seconds. Omitted = no expiry (structural revocation still applies).
-    expiresAt: z.number().int().positive().optional(),
-    label: z.string().min(1).max(200).optional(),
-});
-// Returned on create and on the explicit re-copy intent ONLY — list reads never
-// carry the token-bearing URL (§5.2: share-URL responses are no-store).
-export const shareLinkWithUrlSchema = shareLinkSchema.extend({
-    url: z.string().min(1).describe("https://<host><path>?sf_share=<token>"),
-});
-// Who can open the space — ONE exclusive bit, always explicit. Everything
-// else (password, share links, invites, connection audiences, service tokens)
-// is an additive KEY into a restricted space: union semantics, any key
-// admits; keys are dormant on a public space, never errors. Visibility is
-// DERIVED from the `sharing:` managed block (a restricted space is one whose
-// block carries the space-wide challenge rule) — never stored separately.
-export const SPACE_VISIBILITIES = ["public", "restricted"];
-export const spaceVisibilitySchema = z.enum(SPACE_VISIBILITIES);
-// A connection audience member on the People-only selector state (§6.2/§6.3):
-// "your company SSO" (oidc — optionally narrowed to a verified email domain)
-// or "Acme Shop subscribers" (external — the owner-defined grant tag).
-export const sharingConnectionAudienceSchema = z.object({
-    connectionId: z.string().min(1),
-    // External connections: the grant tag ("wc-subscriber" → ext:{acn}:{tag}).
-    // Required for external, rejected for oidc.
-    tag: z
-        .string()
-        .min(1)
-        .max(100)
-        .regex(/^[A-Za-z0-9._-]+$/)
-        .optional(),
-    // OIDC connections: narrow the audience to a verified email domain — the
-    // rule compiles `email:*@{domain}` instead of `sso:{acn}` (the SSO mint
-    // carries the verified `email:` grant). Rejected for external.
-    emailDomain: z
-        .string()
-        .min(3)
-        .max(255)
-        .regex(/^[a-z0-9.-]+\.[a-z]{2,}$/i)
-        .optional(),
-});
-// PUT …/sharing/visibility — the ONE exclusive choice. Flipping visibility
-// never creates or destroys keys: restricting re-arms whatever keys exist;
-// going public leaves them dormant (including a stored password).
-export const visibilityWriteSchema = z.object({
-    visibility: spaceVisibilitySchema,
-});
-// PUT …/sharing/password — set/replace the password KEY. Setting a password
-// also restricts a public space (the intent is unambiguous); it never touches
-// other keys. DELETE clears the key and leaves visibility alone (fail-closed:
-// a restricted space stays restricted, team-only if that was the last key).
-export const sharingPasswordWriteSchema = z.object({
-    password: z.string().min(1).max(256),
-});
-// PUT …/sharing/audiences — replace the connection-audience keys (§6.2/§6.3).
-// Compiled INTO the one sharing general rule (mixed audiences = one rule,
-// multiple acquires — the chooser is the challenge page, never a new surface).
-export const sharingAudiencesWriteSchema = z.object({
-    audiences: z.array(sharingConnectionAudienceSchema).max(20),
-});
-// The core protection op (agent surface): visibility plus the password key in
-// one write. `password: string` sets the key (and restricts), `null` clears
-// it, omitted leaves it alone. Deeper key management (links, invites,
-// audiences) lives on the sharing surface.
-export const spaceProtectionWriteSchema = z.object({
-    visibility: spaceVisibilitySchema,
-    password: z.string().min(1).max(256).nullable().optional(),
-});
-// A connection audience projected back on the sharing read (derived from the
-// compiled block — never stored separately, X-33).
-export const sharingAudienceSchema = z.object({
-    connectionId: z.string().min(1),
-    type: accessConnectionTypeSchema,
-    // Connection display name (null when the connection row is gone).
-    name: z.string().min(1).nullable().default(null),
-    tag: z.string().min(1).nullable().default(null),
-    emailDomain: z.string().min(1).nullable().default(null),
-    // The compiled requiredGrants entry this audience contributes.
-    grant: grantSchema,
-});
-// A row in the Share modal's People list. Team members are badged; invitees
-// (§5.3) carry their invite id + status so the modal can revoke per-row and
-// badge pending/accepted/expired.
-export const sharingPersonSchema = z.object({
-    kind: z.enum(["team_member", "invitee"]),
-    userId: z.string().min(1).nullable().default(null),
-    email: z.string().min(1).nullable().default(null),
-    name: z.string().min(1).nullable().default(null),
-    // Team management role for members (owner|admin|member); null for invitees.
-    teamRole: z.string().min(1).nullable().default(null),
-    // Space level for invitees (viewer in v1); null for team members.
-    level: spaceLevelSchema.nullable().default(null),
-    // The sin_ invite id for invitees (per-row revoke); null for team members.
-    inviteId: z.string().min(1).nullable().default(null),
-    // Invite lifecycle for invitees ("expired" = the accept LINK lapsed
-    // unaccepted; access-grant compilation is structural, not TTL'd); null for
-    // team members. Revoked invites never appear in the People list.
-    status: z.enum(["pending", "accepted", "expired"]).nullable().default(null),
-    // Operational observability (X-28): per-invitee "last viewed"; null until
-    // the Views ingestion feeds it.
-    lastViewedAt: z.string().min(1).nullable().default(null),
-});
-// ---------------------------------------------------------------------------
-// 3d'. Invites (access-plan §5.3) + access requests (§5.4)
-// ---------------------------------------------------------------------------
-// Accept-link validity (§4.4): how long the emailed magic link mints tokens.
-// Access itself is structural (the invite grant stays compiled until revoke);
-// an expired link only means "re-mail me a new one".
-export const INVITE_ACCEPT_LINK_TTL_SECONDS = 7 * 24 * 60 * 60; // 7 days
-// The visitor token an accept mints (§5.3): 30 days, re-entry by re-clicking
-// the emailed link (X-8: no guest sessions, the inbox is the credential).
-export const INVITE_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60; // 30 days
-// Invite/request personal messages (X-25): ≤280 chars, plain text only —
-// stored as typed, HTML-escaped at every render (email + pages), never
-// linkified, rendered visually subordinate to the platform frame.
-export const ACCESS_MESSAGE_MAX_LENGTH = 280;
-export const INVITE_STATUSES = ["pending", "accepted", "expired", "revoked"];
-export const inviteStatusSchema = z.enum(INVITE_STATUSES);
-// A space invite projected onto the wire (§4.4). The accept token is NEVER
-// stored or returned — only its hash is at rest, and the token travels solely
-// in the invitee's email (possession of the inbox IS the credential). `email`
-// is null once revoked (X-25: invitee addresses are PII of non-users and are
-// purged on revoke; the row survives for audit).
-export const spaceInviteSchema = z.object({
+    scope: accessScopePathSchema,
+    role: accessRoleSchema,
+    createdAt: z.string().datetime(),
+    revokedAt: z.string().datetime().nullable(),
+});
+export const spacePersonStatusSchema = z.enum(["pending", "accepted", "revoked"]);
+export const spacePersonDisplayNameSchema = z.string().trim().min(1).max(160);
+export function fallbackSpacePersonDisplayName(personId) {
+    const suffix = personId.replace(/[^A-Za-z0-9]/gu, "").slice(-6);
+    return suffix ? `Guest ${suffix}` : "Guest";
+}
+export const spacePersonSchema = z.object({
     id: z.string().min(1),
     spaceId: z.string().min(1),
-    email: z.string().min(1).nullable().default(null),
-    invitedBy: z.string().min(1).nullable().default(null),
-    message: z.string().nullable().default(null),
-    status: inviteStatusSchema,
-    // Unix seconds the accept LINK stops minting (re-mail extends it).
-    expiresAt: z.number().int().nonnegative(),
-    acceptedAt: z.string().min(1).nullable().default(null),
-    createdAt: z.string().min(1),
-    // Operational observability (X-28): honest null until the Views ingestion.
-    lastViewedAt: z.string().min(1).nullable().default(null),
-});
-export const spaceInviteCreateSchema = z.object({
-    email: z.string().min(3).max(320),
-    message: z.string().max(ACCESS_MESSAGE_MAX_LENGTH).optional(),
-});
-export const ACCESS_REQUEST_STATUSES = ["pending", "approved", "denied"];
-export const accessRequestStatusSchema = z.enum(ACCESS_REQUEST_STATUSES);
-// An access request (§5.4): a signed-in-but-unsatisfied visitor asking to be
-// let in from the 403 page. Coalesced on (spaceId, email) while pending.
-export const accessRequestSchema = z.object({
+    displayName: spacePersonDisplayNameSchema,
+    email: z.string().email().nullable(),
+    status: spacePersonStatusSchema,
+    grants: z.array(personGrantSchema),
+    invitedBy: z.string().nullable(),
+    inviteExpiresAt: z.string().datetime().nullable(),
+    acceptedAt: z.string().datetime().nullable(),
+    revokedAt: z.string().datetime().nullable(),
+    createdAt: z.string().datetime(),
+});
+export const inheritedTeamAccessSchema = z.object({
+    teamId: z.string().min(1),
+    teamName: z.string().min(1),
+    ruleScopes: z
+        .array(accessScopePathSchema)
+        .min(1)
+        .describe("Explicit team rule locations, not effective subtree coverage."),
+    members: z.array(z.object({
+        membershipId: z.string().min(1),
+        userId: z.string().min(1),
+        displayName: z.string().min(1),
+        email: z.string().email(),
+        teamRole: z.string().min(1),
+        role: z.literal("editor"),
+    })),
+});
+export const spacePeopleListSchema = z.object({
+    people: z.array(spacePersonSchema),
+    inheritedTeamAccess: inheritedTeamAccessSchema.nullable(),
+});
+export const accessShareLinkSchema = z.object({
     id: z.string().min(1),
     spaceId: z.string().min(1),
-    email: z.string().min(1),
-    userId: z.string().min(1).nullable().default(null),
-    host: z.string().min(1),
-    path: z.string().min(1),
-    message: z.string().nullable().default(null),
-    status: accessRequestStatusSchema,
-    resolvedBy: z.string().min(1).nullable().default(null),
-    resolvedAt: z.string().min(1).nullable().default(null),
-    createdAt: z.string().min(1),
-});
-// POST /v1/access/requests — the 403-page form's target. Identity (email +
-// userId) comes from the SESSION, never the body: the authorize chain
-// guarantees requesters are identified (anonymous → 401).
-export const accessRequestCreateSchema = z.object({
-    space: z.string().min(1),
-    host: z.string().min(1).max(255),
-    path: z.string().max(1024).default("/"),
-    nonce: z.string().min(1).max(2048).optional(),
-    message: z.string().max(ACCESS_MESSAGE_MAX_LENGTH).optional(),
-});
-// POST …/requests/:id/approve — the chooser (§5.4): "invite" reuses the §5.3
-// magic-link invite; "team" is the Better-Auth team invitation.
-export const accessRequestApproveSchema = z.object({
-    as: z.enum(["invite", "team"]).default("invite"),
-});
-// File-mode sharing (§5.1 files-mode merge): the dashboard-side file-share
-// rule compiler is dead; file shares are a server-side intent surface owning
-// the `file_share` managed block. A record is keyed by the file/folder PATH;
-// the server expands the serving-path aliases (exact, directory index,
-// extensionless .html variant) at compile time.
-export const FILE_SHARE_AUDIENCES = ["public", "people"];
-export const fileShareAudienceSchema = z.enum(FILE_SHARE_AUDIENCES);
-// The projected file-share record (read shape on the sharing projection).
-export const fileShareSchema = z.object({
-    // Canonical absolute file path ("/report/deck.pdf") or folder path ("/report/").
-    path: z.string().min(1),
-    audience: fileShareAudienceSchema,
-    // The email: grants admitted when audience = "people"; empty for "public".
-    grants: z.array(grantSchema).default([]),
-    // The compiled serving-path alias patterns the record covers (diagnostic).
-    patterns: z.array(z.string().min(1)).default([]),
-});
-// PUT /v1/spaces/:id/file-shares — upsert the record for one path. `grants`
-// accepts raw emails or `email:` grants; the server normalizes + validates.
-export const fileShareWriteSchema = z.object({
-    path: z.string().min(1).max(1024),
-    audience: fileShareAudienceSchema,
-    grants: z.array(z.string().min(1)).max(100).optional(),
-});
-// A pending access request row on the sharing projection (§5.4). `host`/`path`
-// say where the requester was headed so the admin has context.
-export const sharingRequestSchema = z.object({
-    id: z.string().min(1),
-    email: z.string().min(1),
-    message: z.string().nullable().default(null),
-    createdAt: z.string().min(1),
-    host: z.string().min(1).nullable().default(null),
-    path: z.string().min(1).nullable().default(null),
-});
-// ---------------------------------------------------------------------------
-// 3d''. Service tokens (access-plan §4.4/§5.5 — machine principals)
-// ---------------------------------------------------------------------------
-// Service tokens are the machine-principal leg of the IAM table (§5.5):
-// `stk_` rows, Bearer-only, shown ONCE on create, `svc:{id}` grants compiled
-// wherever the token's `actsAs` satisfies, structural revocation (X-7 —
-// revoke recompiles the grant out; the credential's TTL is irrelevant).
-//
-// The secret IS a platform-signed visitor JWT ({sub: "svc:stk_x", grants:
-// ["svc:stk_x"], exp: expiresAt | now+10y}) — the runtime's Bearer path
-// already verifies visitor JWTs before the cookie (§3.2), so CI/agents fetch
-// protected artifacts with `Authorization: Bearer <token>` and ZERO runtime
-// work. Only the token's sha256 is stored (lastUsedAt attribution/display);
-// the plaintext never persists.
-//
-// `sv` posture (documented, accepted): a space-scoped token pins the space's
-// sessionVersion at mint; a team-wide token carries sv 0 (the absent-sv
-// default). A space "logout-all" (sv bump) therefore ALSO rotates service
-// access to that space — re-create the token. Arguably correct: logout-all
-// means "everyone out", and service tokens are visitors too.
-export const SERVICE_TOKEN_DEFAULT_TTL_SECONDS = 10 * 365 * 24 * 60 * 60; // 10 years
-// The audience classes a service token can act as. v1 has exactly one:
-// "viewers" — the token satisfies every managed rule that admits the
-// team-viewer audience (the sharing block's general rule in `link`/`people`
-// modes and file-share `people` rules). It does NOT satisfy a password wall
-// (`pw:` is password-only, like team members) or raw rules that don't name
-// `svc:` grants.
-export const SERVICE_TOKEN_AUDIENCES = ["viewers"];
-export const serviceTokenAudienceSchema = z.enum(SERVICE_TOKEN_AUDIENCES);
-export const serviceTokenActsAsSchema = z.object({
-    audiences: z.array(serviceTokenAudienceSchema).min(1).default(["viewers"]),
-});
-// A service token projected onto the wire — NEVER carries the secret; the
-// signed JWT appears exactly once, on the create response.
-export const serviceTokenSchema = z.object({
-    id: z.string().min(1),
-    teamId: z.string().min(1),
-    // null = team-wide (the grant compiles into every team space).
-    spaceId: z.string().min(1).nullable().default(null),
+    grantId: z.string().min(1),
+    revision: z.number().int().positive(),
     name: z.string().min(1),
-    actsAs: serviceTokenActsAsSchema,
-    // Unix seconds; null = the 10-year default ceiling applies.
-    expiresAt: z.number().int().nonnegative().nullable().default(null),
-    // Operational observability (X-28, mirroring share links): fed by the
-    // runtime access-event ingestion; honest null until that reader lands.
-    lastUsedAt: z.string().min(1).nullable().default(null),
-    createdAt: z.string().min(1),
-    // false once revoked or past expiry — the grant is no longer compiled.
+    landingPath: accessScopePathSchema,
+    resources: grantResourceSetSchema,
+    capabilities: z.array(z.enum(["page.view", "comments.read", "comments.write"])).min(1),
+    constraints: grantConstraintsSchema,
+    target: grantTargetSelectorSchema,
+    createdBy: z.string().nullable(),
+    openCount: z.number().int().nonnegative(),
+    lastUsedAt: z.string().datetime().nullable(),
+    revokedAt: z.string().datetime().nullable(),
+    createdAt: z.string().datetime(),
     active: z.boolean(),
 });
-export const serviceTokenCreateSchema = z.object({
-    name: z.string().min(1).max(200),
-    // Scope the grant to one space; omitted = team-wide.
-    spaceId: z.string().min(1).optional(),
-    // Unix seconds; omitted = the 10-year default. Revocation stays structural
-    // either way — expiry is a hygiene ceiling, not the revocation mechanism.
-    expiresAt: z.number().int().positive().optional(),
-    actsAs: serviceTokenActsAsSchema.optional(),
-});
-// Returned ONLY on create (no-store): the signed Bearer JWT, shown once.
-export const serviceTokenWithSecretSchema = serviceTokenSchema.extend({
-    token: z.string().min(1),
+export const accessShareLinkWithUrlSchema = accessShareLinkSchema.extend({
+    url: z.string().url(),
 });
-// ---------------------------------------------------------------------------
-// 3d'''. The firewall card document (access-plan §5.6, X-15)
-// ---------------------------------------------------------------------------
-// Firewall is rows, not a subsystem (X-15): this document is the SIMPLE
-// altitude — a server-side intent surface that compiles to plain anonymous
-// (deny) or team-viewer challenge ("must sign in") rules in the `firewall`
-// managed block, ordered before `sharing` so a block always beats a link.
-// The projection is DERIVED from the block (X-33-style); rules in the block
-// the projection doesn't recognize flip `custom` and the card sends the user
-// to the raw-rules editor — never to a feature request.
-export const FIREWALL_EFFECTS = ["deny", "challenge"];
-export const firewallEffectSchema = z.enum(FIREWALL_EFFECTS);
-// Country section: `block` denies/challenges the listed countries; `allow`
-// admits ONLY the listed countries (one fail-closed `countryNotIn` rule).
-export const firewallCountriesSchema = z.object({
-    mode: z.enum(["block", "allow"]),
-    // ISO 3166-1 alpha-2, uppercased server-side.
-    list: z
-        .array(z
-        .string()
-        .length(2)
-        .refine((code) => ISO_COUNTRY_CODES.includes(code.toUpperCase()), "Country must be an ISO 3166-1 alpha-2 code."))
+// Reads re-derive the durable branded URL from the sealed token. Links minted
+// before branded URLs existed report null until the backfill mints theirs,
+// rather than pretending to hold a URL that would not open.
+export const accessShareLinkReadSchema = accessShareLinkSchema.extend({
+    url: z.string().url().nullable(),
+});
+// The publish receipt exposes one durable access capability in both of its
+// useful transports: a browser entry URL and the raw token integrations send
+// in X-SF-Authorization. It is access to published bytes, never proof of
+// ownership; claim credentials stay a separate receipt field.
+export const publishedAccessSchema = z.object({
+    url: z.string().url(),
+    token: z.string().min(16).max(512),
+    expiresAt: z.string().datetime().nullable(),
+});
+export const canonicalAccessRequestStatusSchema = z.enum([
+    "verification_pending",
+    "pending",
+    "approved",
+    "denied",
+    "canceled",
+    "expired",
+]);
+export const accessRequestRoleSchema = accessRoleSchema;
+export const canonicalAccessRequestSchema = z.object({
+    id: z.string().min(1),
+    spaceId: z.string().min(1),
+    displayName: spacePersonDisplayNameSchema.nullable(),
+    email: z.string().email(),
+    scope: accessScopePathSchema,
+    requestedRole: accessRequestRoleSchema,
+    message: z.string().nullable(),
+    status: canonicalAccessRequestStatusSchema,
+    emailVerifiedAt: z.string().datetime().nullable(),
+    resolvedBy: z.string().nullable(),
+    resolvedAt: z.string().datetime().nullable(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+});
+export const accessFenceKindValues = ["none", "ownership", "exposure"];
+export const accessFenceKindSchema = z.enum(accessFenceKindValues);
+export const ACCESS_GRANT_SCOPE_LIMIT = 32;
+export const linkCapabilitiesSchema = z
+    .array(z.enum(["page.view", "comments.read", "comments.write"]))
+    .min(1)
+    .refine((capabilities) => capabilities.includes("page.view"), {
+    message: "Link capabilities must include page.view",
+})
+    .refine((capabilities) => new Set(capabilities).size === capabilities.length, {
+    message: "Link capabilities must be unique",
+});
+export const spacePersonInviteWriteSchema = z.object({
+    email: z.string().email(),
+    grants: z
+        .array(z.object({ scope: accessScopePathSchema, role: accessRoleSchema }))
         .min(1)
-        .max(250),
-    // deny = blocked outright; challenge = "visitors from these countries must
-    // sign in" (the team-viewer audience per §5.6).
-    effect: firewallEffectSchema.default("deny"),
-});
-export const firewallIpEntrySchema = z.object({
-    // CIDR ("203.0.113.0/24", v4 or v6) or a bare IP (exact match).
-    cidr: z.string().min(1).max(64),
-    effect: firewallEffectSchema.default("deny"),
-});
-export const firewallBotEntrySchema = z.object({
-    // Case-insensitive user-agent substring (the runtime's `agent` matcher).
-    agent: z.string().min(1).max(200),
-    effect: firewallEffectSchema.default("deny"),
-});
-// PUT /v1/spaces/:id/access/firewall — replaces the recognized firewall-card
-// rules; unrecognized (raw-authored… impossible, managedBy is server-only —
-// i.e. legacy/operator-written) firewall-block rules are PRESERVED and keep
-// the projection's `custom` flag on.
-export const firewallWriteSchema = z.object({
-    countries: firewallCountriesSchema.nullable().default(null),
-    ipCidrs: z.array(firewallIpEntrySchema).max(50).default([]),
-    bots: z.array(firewallBotEntrySchema).max(50).default([]),
-});
-// GET /v1/spaces/:id/access/firewall — the projection derived from the block.
-export const spaceFirewallSchema = z.object({
-    countries: firewallCountriesSchema.nullable().default(null),
-    ipCidrs: z.array(firewallIpEntrySchema).default([]),
-    bots: z.array(firewallBotEntrySchema).default([]),
-    // True when the firewall block holds rules this document can't express —
-    // the card links to the raw-rules editor instead of lying.
-    custom: z.boolean().default(false),
-});
-// ---------------------------------------------------------------------------
-// 3d''''. Team preview-lock (access-plan §4.2/X-24 flagship default)
-// ---------------------------------------------------------------------------
-// "Non-live channels are team-only", configured once for a whole team. The
-// rule `match.channel` is an exact name with no negation, so NOT-live is
-// expressed structurally inside the team_default block (evaluated LAST in the
-// cloud lane): an anonymous allow pinned to the live channel, then a
-// catch-all team-viewer challenge. Live requests terminate on the allow
-// (identical to the no-rule-matches default); anything on another channel
-// falls through to the lock. Because the block is last, every explicit space
-// rule still wins first-match before either rule.
-//
-// These rules are canonical vocabulary (single-homed here): the dashboard
-// toggle and the CLI post exactly these rows through the EXISTING
-// PUT /v1/teams/:id/access/defaults — no second compiler exists.
-export const TEAM_PREVIEW_LOCK_LIVE_RULE_ID = "team-preview-lock:live";
-export const TEAM_PREVIEW_LOCK_RULE_ID = "team-preview-lock";
-export function teamPreviewLockRules(teamId) {
-    return [
-        {
-            id: TEAM_PREVIEW_LOCK_LIVE_RULE_ID,
-            match: { channel: "live" },
-            effect: "allow",
-            reasonCode: "team_preview_lock",
-        },
-        {
-            id: TEAM_PREVIEW_LOCK_RULE_ID,
-            match: {},
-            effect: "challenge",
-            auth: { requiredGrants: [`team:${teamId}:viewer`] },
-            reasonCode: "team_preview_lock",
-            message: "Non-live channels on this team are team-only.",
-        },
-    ];
-}
-export function isTeamPreviewLockRule(rule) {
-    return rule.id === TEAM_PREVIEW_LOCK_LIVE_RULE_ID || rule.id === TEAM_PREVIEW_LOCK_RULE_ID;
-}
-// Whether a team-defaults rule list carries the preview lock.
-export function teamPreviewLockActive(rules) {
-    return rules.some((rule) => rule.id === TEAM_PREVIEW_LOCK_RULE_ID);
-}
-// Toggle helper: returns the defaults list with the lock applied/removed,
-// preserving every other default rule (lock rules ride LAST so other
-// defaults keep first-match precedence within the block).
-export function withTeamPreviewLock(rules, teamId, enabled) {
-    const kept = rules.filter((rule) => !isTeamPreviewLockRule(rule));
-    return enabled ? [...kept, ...teamPreviewLockRules(teamId)] : kept;
-}
-// GET /v1/spaces/:id/sharing — the server-owned projection (X-33): the
-// dashboard renders this and posts intents; it never interprets or compiles
-// rules.
-export const spaceSharingSchema = z.object({
-    // The one exclusive bit. Everything below it is keys.
-    visibility: spaceVisibilitySchema,
-    // Whether the password KEY exists (the verifier hash, never the password).
-    // Independent of visibility: a public space can hold a dormant password.
-    hasPassword: z.boolean(),
-    people: z.array(sharingPersonSchema).default([]),
-    // Connection audiences on the People-only state (§6.2/§6.3), derived from
-    // the compiled sharing block.
-    audiences: z.array(sharingAudienceSchema).default([]),
-    links: z.array(shareLinkSchema).default([]),
-    // Per-path file shares (the `file_share` managed block projected back).
-    fileShares: z.array(fileShareSchema).default([]),
-    requests: z.array(sharingRequestSchema).default([]),
-    // True when rules OUTSIDE the sharing block gate the space (unmanaged cloud
-    // rules or file-lane rules): the modal shows the "custom access rules
-    // active" chip linking to the access settings.
-    customRulesActive: z.boolean(),
-    // Plan-downgrade marker (X-23), mirrored from the access lane read.
-    accessExceedsPlan: z.boolean().default(false),
-});
-// ---------------------------------------------------------------------------
-// 4. Lanes / nouns (additive types only — not wired)
-// ---------------------------------------------------------------------------
-// A channel is a named serving lane (e.g. "live", "staging") pointing at a
-// version, with promote/rollback history.
-export const channelSchema = z.object({
-    name: z.string().min(1),
-    versionId: z.string().min(1),
-    // Newest-first promote/rollback log: which version this channel pointed at.
-    history: z
-        .array(z.object({
-        versionId: z.string().min(1),
-        at: z.string().min(1).describe("ISO 8601 timestamp."),
-    }))
-        .default([]),
-});
-// Content-lane serving config (scalar, field-ownership / SSA semantics). No
-// `spa` toggle — that mode is gone; a SPA is expressed as a `fallback`.
-export const servingConfigSchema = z.object({
-    // Directory index document (e.g. "index.html").
-    index: z.string().min(1).optional(),
-    // Single fallback document served when no file/route matches (replaces the
-    // old `spa` boolean).
-    fallback: z.string().min(1).optional(),
-    // Whether directory listings are rendered when there is no index.
-    listing: z.boolean().optional(),
-});
-// The policy-lane document: an ordered, additive list of unified Rules. This is
-// the firewall+access lane (own version + rollback, independent of content).
-export const policyDocSchema = z.object({
-    rules: z.array(runtimeRuleSchema).default([]),
-    // Space-wide verifier issuers used by first-party access surfaces
-    // (callback/me/token), including public spaces that have no auth rules.
-    issuers: z.array(accessKeySchema).optional(),
-    // Runtime-serving session version. The enforcer rejects visitor tokens whose
-    // `sv` claim does not match and derives local `pw:` keys from this value.
-    sessionVersion: z.number().int().nonnegative().optional(),
-});
-// ---------------------------------------------------------------------------
-// 5. Storage + resolution shapes (additive)
-// ---------------------------------------------------------------------------
-// The CLOUD-stored policy for one space. This is the persisted, versioned form
-// of the policy lane: an ordered list of unified Rules plus a monotonic
-// `version` so the lane can promote/rollback independently of content (mirrors
-// `channelSchema.history`). `version` is bumped on every write; a write that
-// supplies a stale `version` is a lost-update and is rejected by the resolver.
-//
-// Provenance: these are the "cloud" rules. They are merged with any "file"
-// rules compiled from the space's `sf.jsonc` (which travel + roll back
-// WITH a content version) to produce the effective policy — see
-// `effectiveRuleSchema` / `effectivePolicySchema`.
-export const spacePolicySchema = z.object({
-    // Ordered, additive Rules (first-match-wins at serving compile time). Same
-    // unified Rule the runtime verifies; an absent `auth` is an anonymous
-    // firewall rule (firewall ⊂ access).
-    rules: z.array(runtimeRuleSchema).default([]),
-    // Monotonic lane version. Starts at 1 on first write; every accepted write
-    // increments it. Used for optimistic concurrency (lost-update rejection) and
-    // for rollback to a prior lane revision.
-    version: z.number().int().nonnegative().default(0),
-});
-// GET/PUT /v1/spaces/:id/access-rules wire schemas — the ordered, always-latest
-// access policy pair. Shared by the still-mounted /access route family and the
-// detached /access-rules core adapter so activation has exactly one schema to
-// retire, not two to reconcile.
-export const spaceAccessRulesWriteSchema = z.object({
-    rules: z.array(runtimeRuleSchema).default([]),
-    expectedVersion: z.number().int().nonnegative().optional(),
-});
-// The lane read plus the plan-downgrade marker (access-plan X-23): plan-gated
-// rules keep enforcing after a downgrade; this flag is the notice surface.
-export const spaceAccessRulesReadSchema = spacePolicySchema.extend({
-    accessExceedsPlan: z.boolean().default(false),
-});
-// PUT/DELETE /v1/spaces/:id/quick-share wire schemas — the one active
-// whole-space guest link (§5.2).
-export const quickShareSchema = z.object({
-    kind: z.literal("quick_share"),
+        .max(ACCESS_GRANT_SCOPE_LIMIT),
+});
+export const personGrantWriteSchema = z.object({
+    scope: accessScopePathSchema,
+    role: accessRoleSchema,
+});
+export const spacePersonGrantSetWriteSchema = z.object({
+    grants: z.array(personGrantWriteSchema).min(1).max(ACCESS_GRANT_SCOPE_LIMIT),
+});
+export const accessShareLinkCreateSchema = z.object({
+    name: z.string().trim().min(1).max(200),
+    landingPath: accessScopePathSchema.default("/"),
+    resources: grantResourceSetSchema,
+    // Anonymous commenting is a product default: a Link that names no
+    // capabilities admits reading the page and leaving a comment.
+    capabilities: linkCapabilitiesSchema.default(["page.view", "comments.read", "comments.write"]),
+    constraints: grantConstraintsSchema.default({}),
+    target: grantTargetSelectorSchema.default({ kind: "live" }),
+});
+export const accessShareLinkUpdateSchema = z.object({
+    expectedRevision: z.number().int().positive(),
+    name: z.string().trim().min(1).max(200).optional(),
+    landingPath: accessScopePathSchema.optional(),
+    resources: grantResourceSetSchema.optional(),
+    capabilities: linkCapabilitiesSchema.optional(),
+    constraints: grantConstraintsPatchSchema.optional(),
+    target: grantTargetSelectorSchema.optional(),
+});
+export const canonicalAccessRequestCreateSchema = z.object({
+    email: z.string().email(),
+    scope: accessScopePathSchema,
+    requestedRole: accessRequestRoleSchema.default("viewer"),
+    message: z.string().max(280).optional(),
+});
+export const canonicalAccessRequestApproveSchema = z.object({
+    scope: accessScopePathSchema.optional(),
+    role: accessRoleSchema.optional(),
+});
+export const openHandoffSchema = z.object({
     url: z.string().url(),
-    expiresAt: z.string().min(1),
-    outcome: z.enum(["created", "reused"]),
+    expiresAt: z.string().datetime(),
+    kind: z.enum(["management", "claim_preview", "person"]),
 });
-export const quickShareDeleteSchema = z.object({
-    outcome: z.enum(["deleted", "unchanged"]),
+export const openLinkSchema = z.object({
+    url: z.string().url(),
+    expiresAt: z.string().datetime().nullable(),
+    kind: z.literal("link"),
 });
-// GET/PUT /v1/spaces/:id/enhancements wire schemas — whole-space page
-// enhancements (analytics, tag manager, custom scripts) on/off. `active` is
-// reserved and currently always empty (see the composition delta on
-// spaces/enhancements-service.ts).
-export const enhancementsSchema = z.object({
-    enabled: z.boolean(),
-    active: z.array(z.string()),
+export const privateOpenSchema = z.union([openLinkSchema, openHandoffSchema]);
+export const openHandoffCreateSchema = z.object({
+    landingPath: accessScopePathSchema.default("/"),
+    targetHost: z.string().trim().min(1).max(255).optional(),
 });
-export const enhancementsWriteSchema = z.object({ enabled: z.boolean() });
-// Where an effective rule came from. `platform` = composed by the cloud from
-// platform state (plan window, abuse/ban/billing) and PREPENDED above every
-// user-authored rule so a platform decision always wins first-match-wins; the
-// user can NEVER author a `platform` rule. `file` = compiled from the space's
-// `sf.jsonc` (timeless, rolls back with the content version). `cloud` =
-// the stored `spacePolicySchema` lane (incident interventions, password walls
-// set via the API/CLI, etc.). Provenance is surfaced so an operator reading the
-// effective policy can tell which surface to edit to change a given rule.
-export const ruleSourceSchema = z.enum(["platform", "file", "cloud"]);
-// A provenance-annotated effective Rule: the unified `runtimeRuleSchema` plus
-// the `source` it was contributed by and the `order` it occupies in the
-// resolved, first-match-wins list. This is the READ shape returned by the
-// effective-policy resolver — never stored. `order` is the 0-based index in the
-// flattened effective list (file rules then cloud rules, or whatever order the
-// resolver composes), letting a caller reconstruct match precedence.
-export const effectiveRuleSchema = runtimeRuleSchema.extend({
-    source: ruleSourceSchema,
-    order: z.number().int().nonnegative(),
+export const teamSpaceAccessDefaultSchema = z.object({
+    newSpaceGrantPreset: spaceAccessPresetSchema,
 });
-// The resolved effective policy for a space: the flattened, provenance-tagged
-// rule list plus the `cloudVersion` (the `spacePolicySchema.version` the cloud
-// rules were resolved from) so a reader can detect drift / pin a write against
-// the revision it observed. `fileVersion` is the content version id the `file`
-// rules were compiled from (null when the space has no compiled file rules).
-export const effectivePolicySchema = z.object({
-    rules: z.array(effectiveRuleSchema).default([]),
-    // Space-wide verifier issuers. The control plane always emits the platform
-    // issuer here so identity-only public-space tokens verify without a rule.
-    issuers: z.array(accessKeySchema).default([]),
-    cloudVersion: z.number().int().nonnegative().default(0),
-    fileVersion: z.string().min(1).nullable().default(null),
-    // Serving-secret map (name -> value) the resolved rules reference by
-    // password-acquire `ref` = "secret:<name>". Carries the space password's
-    // bcrypt verifier hash, keyed so the runtime resolves it from
-    // `serving['secrets']` and `password_verify`s against it. Never contains
-    // plaintext the visitor types — only stored verifier hashes / shared secrets.
-    secrets: z.record(z.string().min(1), z.string().min(1)).default({}),
-    // Space session version (access-plan §3.1/§4.4): visitor tokens must carry a
-    // matching `sv` claim. Bumped by logout-all; also an input to the space-local
-    // `pw:` key derivation, so a bump invalidates every wall pass with zero new
-    // state.
-    sessionVersion: z.number().int().nonnegative().default(0),
+export const teamSpaceAccessDefaultWriteSchema = z.object({
+    newSpaceGrantPreset: spaceAccessPresetSchema,
 });
 // ---------------------------------------------------------------------------
-// 6. Simulate (access-plan §5.5, X-13)
+// Unified visitor and collaboration tokens
 // ---------------------------------------------------------------------------
-// GET /v1/spaces/:id/access/simulate?host&path[&email&ip&country] → the rule
-// that would fire and why. Runs on the parity-pinned TS matcher, so simulate
-// correctness is a corollary of the corpus.
-export const accessSimulateResultSchema = z.object({
-    verdict: z.enum(["allow", "deny", "challenge"]),
-    // The first effective rule (with lane/source + order) whose match applies
-    // and whose effect resolves for the simulated identity; null = no rule
-    // gates the request (public).
-    matchedRule: effectiveRuleSchema.nullable().default(null),
-    // The matched rule's requiredGrants — which grants would satisfy it.
-    why: z.array(grantSchema).default([]),
-    // Human audience summary derived from requiredGrants ("Team members",
-    // "Anyone with an active share link", …).
-    whoWouldPass: z.array(z.string()).default([]),
+export const ACCESS_TOKEN_KID = "spacefast-runtime-v1";
+export const ACCESS_TOKEN_ALG = "EdDSA";
+export const RUNTIME_JWKS_WELL_KNOWN_FILENAME = "spacefast-runtime-jwks.json";
+// Public identity attached only when a token consumer needs to render the
+// person behind an authority. Collaboration tickets carry this audience-bound
+// claim so Cast can paint an avatar without ever seeing an address: the
+// minting side normalizes a provider avatar or derives one from the email,
+// then drops the email. Raw email and provider-private profile metadata never
+// belong here.
+export const accessTokenPublicProfileSchema = z
+    .object({
+    name: z.string().min(1).max(120).optional(),
+    username: z.string().min(1).max(160).optional(),
+    avatar_url: z
+        .url({ protocol: /^https?$/ })
+        .max(2_048)
+        .optional(),
+})
+    .strict();
+export const accessTokenPayloadSchema = z.object({
+    sub: authorityReferenceSchema,
+    // Who this handoff authenticated, when it authenticated anybody. The account
+    // lane names the signed-in user; the invite and identity-connection lanes
+    // name the Person or external subject they just proved. Link, password,
+    // machine, and claim-preview lanes never set it, and its absence means the
+    // runtime session is anonymous. Identity comes from here alone — never
+    // inferred from the authority classes below.
+    principal: identifiedPrincipalSchema.optional(),
+    authorities: z.array(authorityReferenceSchema).min(1).max(16),
+    exp: z.number().int().nonnegative(),
+    nbf: z.number().int().nonnegative(),
+    iat: z.number().int().nonnegative(),
+    iss: z.string().min(1),
+    aud: z.string().min(1),
+    spaceId: z.string().min(1),
+    // Shared opaque identity for the runtime session and its access-origin
+    // collaboration session. It is random per handoff and never authorizes by itself.
+    sid: z.string().regex(/^[a-f0-9]{64}$/),
+    generation: z.number().int().nonnegative(),
+    emailVerified: z.boolean().default(false),
+    profile: accessTokenPublicProfileSchema.optional(),
+    jti: z.string().min(1),
 });