@spacefast/common 0.0.3 → 0.0.6

package/dist/contracts/access.js

@@ -1,13 +1,15 @@
 import { z } from "zod";
-// Unified access contracts (internal-docs/stattic-model-plan.html "Section I ·
-// access" + internal-docs/access-management-plan.md).
+// Unified access contracts (internal-docs/access-plan.html — the only access
+// document).
 //
-// Unified access contracts (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. The
-// runtime enforces a verifiable subset (password secret-compare + token
-// Ed25519/grant-intersection + anonymous firewall); the cloud resolves identity
-// and mints signed tokens. Field names are the spec contract — do not rename.
+// 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.
 // ---------------------------------------------------------------------------
 // 1. Grants
 // ---------------------------------------------------------------------------
@@ -19,35 +21,41 @@ import { z } from "zod";
 // `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)
+//   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
-//   svc:<tokenId>               a service token (CI, agents)
-//   ext:{connectionId}:<tag>    an owner-defined external grant
+//   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)
 //
-// Tokens signed by an external (BYO) key may only carry grants namespaced to
-// that key (see `accessKeySchema.grantNamespaces`); everything else is dropped
-// before intersection.
+// 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. Useful for validation/UX; not exhaustive of
-// every future namespace, but covers the documented vocabulary.
+// Known grant namespace prefixes — final vocabulary (access-plan §1).
 export const GRANT_NAMESPACES = [
     "email:",
     "team:",
     "sub-team:",
     "user:",
-    "svc:",
-    "ext:",
-    // Mint-time-only namespaces (sources the cloud resolves into the above, plus
-    // transient grants the runtime mints itself).
-    "email-domain:",
     "space:",
     "link:",
+    "invite:",
+    "svc:",
     "sso:",
-    "pw:", // minted by a form-transport password challenge
+    "ext:",
+    "pw:",
 ];
-const GRANT_PATTERN = /^(email|email-domain|team|sub-team|user|svc|ext|space|link|sso|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
@@ -61,6 +69,12 @@ export function isWellFormedGrant(grant) {
 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
 // ---------------------------------------------------------------------------
@@ -74,29 +88,227 @@ export const accessKeySchema = z.object({
     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:","email-domain:","space:","link:","svc:","sso:"]);
+    // (["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/host baked in). 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 parseConnectionAcquireRef(url) {
+    if (!url.startsWith("connection:")) {
+        return null;
+    }
+    const id = url.slice("connection:".length);
+    return id.length > 0 && !id.includes("/") && !id.includes(":") ? id : null;
+}
+// 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);
+            }
+        }
+    }
+    for (const acquire of input.acquire ?? []) {
+        if (acquire.type === "login" && acquire.url) {
+            const id = parseConnectionAcquireRef(acquire.url);
+            if (id) {
+                ids.add(id);
+            }
+        }
+    }
+    return [...ids];
+}
+// 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
+    .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: pass when EITHER the password OR the token leg is
-// satisfied. Folds the old basicAuth / sso / login / composite requirement
-// types into two legs. An absent `auth` makes the rule an anonymous firewall
-// rule (effect applies on match, no credential needed) — this is the sense in
-// which **firewall ⊂ access**.
-export const passwordAuthSchema = z.object({
-    // A secret reference (e.g. "secret:site_pw"), never plaintext. The runtime
-    // resolves it from serving secrets and compares.
+// 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),
-    // `basic` = stateless HTTP Basic 401 challenge. `form` = renders the password
-    // wall, and on success mints a short-lived `pw:` grant cookie.
     transport: z.enum(["basic", "form"]),
     username: z.string().min(1).optional(),
 });
-export const tokenAuthSchema = z.object({
+export const loginAcquireSchema = z.object({
+    type: z.literal("login"),
+    // Interactive login surface the challenge page links to (the cloud authorize
+    // endpoint, or a BYO connection's authorizeUrl). Hydrated by the compiler;
+    // the runtime appends `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),
@@ -104,26 +316,19 @@ export const tokenAuthSchema = z.object({
     // 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(),
-    // Interactive login surface the runtime 302-redirects an unsatisfied browser
-    // visitor to (with an opaque `return=` param). Absent = no interactive login
-    // (service-token-only rule) and the runtime denies a browser rather than loop.
-    loginUrl: z.string().min(1).optional(),
-    // Cookie name the runtime reads the visitor token from (default
-    // `stattic_access`); the Authorization Bearer header always takes precedence.
-    cookieName: z.string().min(1).optional(),
-});
-export const ruleAuthSchema = z
-    .object({
-    password: passwordAuthSchema.optional(),
-    token: tokenAuthSchema.optional(),
-})
-    .refine((a) => a.password !== undefined || a.token !== undefined, {
-    message: "auth must specify at least one of `password` or `token`",
+    // 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").
@@ -137,46 +342,68 @@ export const ruleMatchSchema = z.object({
     // 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 the password OR token leg is satisfied.
+    // 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.
+    // 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 default cookie the runtime reads a visitor token from when a rule's token
-// leg names no explicit `cookieName` (see access-rules.php
-// `_stattic_unified_token_from_request`). The authorize endpoint sets the
-// minted token under this name so the very next request to the protected host
-// carries it.
-export const ACCESS_TOKEN_COOKIE_NAME = "stattic_access";
 // The header `kid`/`alg` the platform signs visitor tokens with. These match
-// the runtime JWKS key (`stattic-runtime-v1` / EdDSA) so the runtime's
-// JWKS-by-kid verify (access-rules.php) accepts a token the cloud minted. Do
+// 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 = "stattic-runtime-v1";
+export const ACCESS_TOKEN_KID = "spacefast-runtime-v1";
 export const ACCESS_TOKEN_ALG = "EdDSA";
-// The DEDICATED `kid` Cast access tokens are signed under (CAST-NATIVE-PLAN
-// decision D-1). It is published in the SAME JWKS as the runtime key, but is
-// distinct so the runtime's JWKS-by-kid verify (which only accepts
-// `ACCESS_TOKEN_KID`) refuses a Cast token outright, decoupling Cast key
-// rotation from the runtime. Cast selects the verifying key by this `kid`.
-export const CAST_TOKEN_KID = "spacefast-cast-v1";
+// 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.
+    // 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.
@@ -189,19 +416,25 @@ export const accessTokenPayloadSchema = z.object({
     // 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(),
 });
-// Authorize request: the bounded authenticated-team-member mint path. The
-// caller is already an authenticated session; the body only tunes the mint.
-// `setCookie` (default true) asks the endpoint to also set the access cookie so
-// the next navigation to the protected host is authorized without the client
-// re-attaching the token. `aud` optionally binds the token to one host.
+// 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({
-    setCookie: z.boolean().default(true),
     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) and whether the access
-// cookie was set on the response.
+// 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),
@@ -209,100 +442,458 @@ export const authorizeResponseSchema = z.object({
     payload: accessTokenPayloadSchema,
     // Unix seconds the token expires at (convenience mirror of `payload.exp`).
     expiresAt: z.number().int().nonnegative(),
-    // The cookie name the token was set under, or null when `setCookie` was false.
-    cookieName: z.string().min(1).nullable().default(null),
+});
+// ---------------------------------------------------------------------------
+// 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(),
 });
 // ---------------------------------------------------------------------------
 // 3c. Mint-time grant builders (the cloud "resolve identity → grants" half)
 // ---------------------------------------------------------------------------
-// The concrete grant a space invitee carries once they accept: a token with
-// `space:{spaceId}:viewer` intersects the `invited`-audience rule the compiler
-// emits (`requiredGrants: ["space:{spaceId}:viewer"]` + team grants, §6.3).
-// The platform issuer lists the `space:` namespace, so the runtime keeps it.
-export function spaceViewerGrant(spaceId) {
-    return `space:${spaceId}:viewer`;
-}
-// The leveled space grant an invited reviewer carries (CAST-NATIVE-PLAN D-2/
-// D-4): `space:{spaceId}:{level}` where level ∈ viewer|commenter|editor. The
-// `space:` namespace is on the platform issuer (resolve.ts `platformIssuer`), so
-// the runtime keeps it; Cast reads the level off the token to key its
-// capability table. `spaceViewerGrant` is the `viewer` special case kept for the
-// accepted-invite path; this is the general leveled form the reviewer people
-// layer reconciles and the Cast mint carries.
+// 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}`;
 }
 // The concrete grant a share-link holder carries: a token with `link:{linkId}`
-// intersects the `shareLinks`-audience rule whose `requiredGrants` the compiler
-// fills from the ACTIVE link rows (§6.4). Revoking the link recompiles it out
+// 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}`;
 }
+// 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 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}`;
+}
 // ---------------------------------------------------------------------------
-// 3d. Invite + share-link mint surface (request/response contracts)
+// 3d. Share links + the sharing projection (access-plan §5.1/§5.2, X-33)
 // ---------------------------------------------------------------------------
-//
-// ADDITIVE / NOT-YET-WIRED: the request/response shapes for the invite and
-// share-link minting endpoints described in access-management-plan.md §6.3/§6.4
-// and §9. The persistence (the `spaceInvites` / `shareLinks` tables, magic-token
-// hashing, accept/create/revoke routes, the recompile-on-revoke step, and the
-// request-access loop) needs DB migrations + email and is specified in
-// internal-docs/invite-minting-plan.md — these schemas are the contract that
-// plan's endpoints will validate against, safe to land first.
-// `POST /v1/spaces/:id/invites` body (§6.3). Invites a single email as a space
-// viewer. The email is lowercased + NFC-normalized server-side before storage.
-export const inviteCreateRequestSchema = z.object({
-    email: z.string().email(),
-    // Optional invite-link validity in days (default 7d at the route).
-    expiresInDays: z.number().int().positive().max(365).optional(),
-    // Optional note shown in the invite email.
-    message: z.string().max(300).optional(),
-});
-// A pending/accepted/revoked invite as surfaced to owners. The magic token is
-// NEVER returned — only its lifecycle. `id` is `sin_…`.
+// Share tokens are re-signed on demand from the link row (§5.2): the JWT is
+// never stored, only the row. `exp` = the link's expiry capped at this ceiling
+// (and re-copying re-mints, so a live link's URL never goes stale).
+export const SHARE_LINK_TOKEN_MAX_TTL_SECONDS = 30 * 24 * 60 * 60; // 30 days
+// 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({
+    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 (tokens still cap at 30d and
+    // re-mint from the row on copy).
+    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>"),
+});
+// The Share modal's General-access selector (§5.1). The mode is DERIVED from
+// the `sharing:` managed block — never stored separately — so "who can see
+// this" has exactly one home.
+export const GENERAL_ACCESS_MODES = ["public", "password", "link", "people"];
+export const generalAccessModeSchema = z.enum(GENERAL_ACCESS_MODES);
+// 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(),
+});
+export const generalAccessWriteSchema = z.object({
+    mode: generalAccessModeSchema,
+    // Required when switching to "password" for the first time; optional when a
+    // stored password already exists (it is kept).
+    password: z.string().min(1).max(256).optional(),
+    // People-mode connection audiences (§6.4): compiled INTO the one sharing
+    // general rule (mixed audiences = one rule, multiple acquires — the chooser
+    // is the challenge page, never a new surface). Omitted = keep the current
+    // audiences; [] = remove them.
+    audiences: z.array(sharingConnectionAudienceSchema).max(20).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({
     id: z.string().min(1),
     spaceId: z.string().min(1),
-    email: z.string().email(),
-    status: z.enum(["pending", "accepted", "revoked", "expired"]),
-    // The viewer grant this invite mints on acceptance — surfaced so the owner can
-    // see exactly what it grants (`space:{spaceId}:viewer`).
-    grant: z.string().min(1),
+    email: z.string().min(1).nullable().default(null),
     invitedBy: z.string().min(1).nullable().default(null),
-    expiresAt: 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),
-    revokedAt: 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),
 });
-// `POST /v1/spaces/:id/share-links` body (§6.4). Creates an "anyone with the
-// link" grant scoped to a path prefix, with an optional expiry + label.
-export const shareLinkCreateRequestSchema = z.object({
-    // "/" = the whole space. Must be an absolute, backslash-free path.
-    pathPrefix: z
-        .string()
-        .regex(/^\/[^\\]*$/)
-        .default("/"),
-    // Absent = a non-expiring link.
-    expiresAt: z.string().min(1).optional(),
-    label: z.string().max(120).optional(),
-});
-// A share link as surfaced to owners. `url` (the token-bearing URL) is returned
-// ONLY on the create response (the runtime trades `?stattic_share=` for a
-// cookie once); list/read responses omit it and show only the lifecycle. `id`
-// is `lnk_…`; `grant` is `link:{id}`.
-export const shareLinkSchema = z.object({
+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({
     id: z.string().min(1),
     spaceId: z.string().min(1),
-    pathPrefix: z.string().min(1),
-    label: z.string().nullable().default(null),
-    grant: z.string().min(1),
-    // The token-bearing URL — present only on create; null on list/read.
-    url: z.string().min(1).nullable().default(null),
-    createdBy: z.string().min(1).nullable().default(null),
-    expiresAt: z.string().min(1).nullable().default(null),
-    revokedAt: z.string().min(1).nullable().default(null),
+    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),
+    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.
+    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),
+});
+// ---------------------------------------------------------------------------
+// 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 (the compiler enumerates the complement —
+// rule `match.country` is an exact ISO code with no negation, so allow-mode
+// is expressed as one rule per non-listed country).
+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)).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({
+    generalAccess: z.object({
+        mode: generalAccessModeSchema,
+        // Whether a stored space password exists (the verifier hash, never the
+        // password) — lets the modal say "keep existing 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)
@@ -335,6 +926,12 @@ export const servingConfigSchema = z.object({
 // 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)
@@ -385,12 +982,38 @@ export const effectiveRuleSchema = runtimeRuleSchema.extend({
 // 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
-    // `auth.password.ref` = "secret:<name>". Today this carries the space
-    // password's bcrypt verifier hash, keyed so the runtime resolves it from
+    // 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),
+});
+// ---------------------------------------------------------------------------
+// 6. Simulate (access-plan §5.5, X-13)
+// ---------------------------------------------------------------------------
+// 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([]),
 });