@spacefast/common 0.0.26 → 0.2.2

package/dist/config/domains.js

@@ -1,17 +1,15 @@
-// THE single source of truth for Spacefast hostnames and per-service origins,
-// across every environment. Brand strings, app URL builders, CORS allowlists,
-// cookie scope, and redirect rules all derive from here so a domain change is a
-// one-file edit instead of the ~100-site sweep this migration had to untangle.
+// THE single source of truth for Spacefast hostnames and per-service origins.
+// Brand strings, app URL builders, CORS allowlists, cookie scope, and redirect
+// rules all derive from here, so a domain change is a one-file edit.
 //
-// Env-var NAMES intentionally stay `SPACEFAST_*` (see migration plan); only the
-// VALUES they carry are produced from this registry.
+// Env-var NAMES stay `SPACEFAST_*`; only the VALUES come from this registry.
 /** The production apex. Everything else about prod derives from this string. */
 export const PROD_ENV_DOMAIN = "spacefast.com";
 /** The local-dev apex (portless serves every subdomain over HTTPS). */
 export const DEV_ENV_DOMAIN = "sf.localhost";
 /** The deployed staging apex. Not local: staging is a hosted environment. */
 export const STAGING_ENV_DOMAIN = "stattic.net";
-/** The deployed dev apex — distinct from local dev, which stays on sf.localhost. */
+/** The deployed dev apex. Local dev is separate and stays on sf.localhost. */
 export const DEV_DEPLOY_ENV_DOMAIN = "stattic.xyz";
 export const HOSTED_ENV_DOMAINS = {
     dev: DEV_DEPLOY_ENV_DOMAIN,
@@ -37,12 +35,11 @@ export function hostedEnvDomain(environment) {
     return hosted ? HOSTED_ENV_DOMAINS[hosted] : null;
 }
 /**
- * Construct the full per-service host map from a single env domain
- * (`spacefast.com`, `stattic.net`, `sf.localhost`, …). One knob — services are
- * always `<service>.<domain>` over https, with three deliberate exceptions: the
- * marketing site sits on the bare apex of a hosted environment (so staging
- * rehearses production's shape rather than a `www.` variant of it), and both
- * Git push and the internal handbook live on their own apexes in prod.
+ * The per-service host map for one env domain (`spacefast.com`, `sf.localhost`,
+ * …). Services are `<service>.<domain>` over https, with three exceptions: the
+ * marketing site takes the bare apex of a hosted environment (so staging
+ * rehearses production's shape), and Git push and the internal handbook get
+ * their own apexes in prod.
  */
 export function envDomainsFor(domain) {
     const prod = domain === PROD_ENV_DOMAIN;
@@ -65,13 +62,11 @@ export function envDomainsFor(domain) {
     };
 }
 const PROD = envDomainsFor(PROD_ENV_DOMAIN);
-// Local dev runs every service under *.sf.localhost via portless (HTTPS, no
-// ports in the URL — portless proxies the raw dev ports). `remove all other
-// portless records` per the migration spec: sf.localhost is the only TLD.
+// Local dev runs every service under *.sf.localhost via portless, which proxies
+// the raw dev ports so URLs carry no port. sf.localhost is the only local TLD.
 const DEV = envDomainsFor(DEV_ENV_DOMAIN);
-// The test stack shares the sf.localhost hostname scheme but runs as its own
-// isolated compose project on its own ports/resources (see ports config), so it
-// can run side-by-side with dev. URL host scheme is identical to dev.
+// The test stack uses dev's hostname scheme but its own isolated compose project
+// and ports (see ports config), so the two run side by side.
 const TEST = DEV;
 const BY_ENV = {
     dev: DEV,
@@ -83,8 +78,16 @@ export function serviceOrigin(service, env) {
     const d = BY_ENV[env];
     return `${d.protocol}://${d.hosts[service]}`;
 }
-/** Base URL every documentation link — catalog entries, skills, error pages — resolves against. */
+/** Base URL every documentation link resolves against: catalog entries, skills, error pages. */
 export const DOCS_BASE_URL = `${serviceOrigin("www", "prod")}/docs`;
+/**
+ * The API origin every first-party client falls back to when nothing else names
+ * a provider: no `--api-url`, no `SPACEFAST_API_URL`, no saved profile or
+ * checkout link. The CLI and the MCP server share this one literal so a caller
+ * cannot be pointed at two different "defaults" depending on which surface it
+ * came through.
+ */
+export const DEFAULT_API_URL = serviceOrigin("api", "prod");
 // --- Apexes that are NOT spacefast.com subdomains -------------------------------
 /**
  * The production infrastructure apex. Committed artifacts and anything
@@ -98,29 +101,24 @@ export const DEV_VIEW_FAST_APEX = "preview.space";
 /**
  * Resolve the infrastructure apex, allowing an explicit deployment override.
  *
- * Only production has an apex here. Every other hosted environment names its
- * own through `SPACEFAST_VIEW_FAST_APEX`, because a space apex is a zone that
- * has to exist, be delegated, and be attached at the provider — not a name this
- * registry can pick on a deployment's behalf. Two environments allocating from
- * one apex race for the same hostname, and the one that loses is a customer's
- * site.
+ * Only production has an apex here. Every other hosted environment names its own
+ * through `SPACEFAST_VIEW_FAST_APEX`, because a space apex is a zone that must
+ * exist, be delegated, and be attached at the provider. Two environments
+ * allocating from one apex race for the same hostname, and the loser is a
+ * customer's site.
  *
- * When nothing names the apex, this falls back to the local one rather than
- * production's: a caller that cannot say which environment it is has no claim
- * on production's namespace. Holding deployments to naming it belongs to the
- * process that mints hostnames, not to this module — the control plane's env
- * schema refuses to boot without it, while builds and browser bundles import
- * this registry for its host scheme and must not explode over an environment
- * they do not have.
+ * When nothing names the apex this falls back to the local one: a caller that
+ * cannot say which environment it is has no claim on production's namespace. The
+ * control plane's env schema is what holds deployments to naming it; builds and
+ * browser bundles import this registry only for its host scheme.
  */
 export function resolveViewFastApex(environment) {
     const explicit = environment.SPACEFAST_VIEW_FAST_APEX?.trim().toLowerCase();
     if (explicit)
         return explicit;
     // SPACEFAST_ENV names a hosted environment only on a deployed service, where
-    // NODE_ENV is production — the same split the control plane's env-domain
-    // derivation makes. `dev` is also the local stack's name, and a local stack
-    // must keep the local apex rather than allocate under hosted dev's.
+    // NODE_ENV is production. `dev` is also the local stack's name, and a local
+    // stack must keep the local apex rather than allocate under hosted dev's.
     const nodeEnvironment = environment.NODE_ENV?.trim().toLowerCase();
     if (!["prod", "production"].includes(nodeEnvironment ?? ""))
         return DEV_VIEW_FAST_APEX;
@@ -130,8 +128,54 @@ export function resolveViewFastApex(environment) {
 }
 /** Infrastructure apex used for public managed/custom domains. */
 export const VIEW_FAST_APEX = resolveViewFastApex(typeof process === "undefined" ? {} : process.env);
-// Default space hostnames are `{hostLabel}.{VIEW_FAST_APEX}`; internal
-// management hostnames share the same apex under the reserved `wpc-manage-`
-// label prefix and are never public space URLs.
-/** Reserved first-label prefix for the management namespace; users may not register it. */
-export const MANAGEMENT_LABEL_PREFIX = "wpc-manage-";
+// Default space hostnames are `{hostLabel}.{VIEW_FAST_APEX}`.
+// --- Test-mode (simulated) apex -------------------------------------------------
+/**
+ * The Spacefast-owned apex under which a LINKED TEST TENANT's simulated sites and
+ * hostname namespaces materialize (partner-operations spec §1). It is never
+ * served by real infrastructure — nothing points DNS at it and no cert is
+ * provisioned — so it exists purely as a collision-free namespace: a test
+ * tenant's hostnames are `{label}.{tenant}.{TEST_APEX}` (per-tenant, see
+ * `testApexForTenant`), which is also the marker the runtime-API transport uses
+ * to recognize a simulated box and short-circuit rather than reach a real one.
+ *
+ * Defaults to `test.{VIEW_FAST_APEX}` so every environment gets a distinct test
+ * apex for free; a deployment can override it with `SPACEFAST_TEST_APEX`.
+ */
+export function resolveTestApex(environment) {
+    const explicit = environment.SPACEFAST_TEST_APEX?.trim().toLowerCase();
+    if (explicit)
+        return explicit;
+    return `test.${resolveViewFastApex(environment)}`;
+}
+/** The resolved test-mode apex for this process. */
+// oxlint-disable-next-line anti-slop/no-runtime-typeof -- isomorphic process guard: this registry is imported by browser bundles where `process` is undefined (same guard as VIEW_FAST_APEX above).
+export const TEST_APEX = resolveTestApex(typeof process === "undefined" ? {} : process.env);
+// A tenant id (`ten_<rand>`) as a DNS label: lowercase, `_`→`-`, non-label chars
+// dropped. Every test tenant gets its OWN apex under `TEST_APEX` so the GLOBAL
+// `hostname_namespace_apex_uq` never collides at the second test tenant, and so
+// a test label can never steer a live space.
+export function testApexForTenant(tenantId, testApex = TEST_APEX) {
+    const label = tenantId
+        .trim()
+        .toLowerCase()
+        .replaceAll("_", "-")
+        .replace(/[^a-z0-9-]/g, "")
+        .replace(/^-+|-+$/g, "");
+    return `${label || "tenant"}.${testApex}`;
+}
+/**
+ * Whether a hostname belongs to the test-mode apex (a simulated box).
+ *
+ * STRICTLY a suffix check — the apex ITSELF is never a simulated hostname. Every
+ * simulated hostname is `{label}.{tenant}.{TEST_APEX}` (two labels deep), while
+ * the bare apex is reachable as a LIVE space's hostname: `TEST_APEX` defaults to
+ * `test.{VIEW_FAST_APEX}`, so a live space slugged `test` is served at exactly
+ * `test.view.fast`. Matching the apex would make every Runtime-API call for that
+ * space short-circuit to a synthetic response — engine installs reporting
+ * `installed` and publishes reporting success while nothing ever reaches the box.
+ */
+export function isTestApexHostname(hostname, testApex = TEST_APEX) {
+    const normalized = hostname.trim().toLowerCase().replace(/\.$/, "");
+    return normalized.endsWith(`.${testApex}`);
+}

package/dist/config/index.js

@@ -1,3 +1,2 @@
-// Public entry for the centralized domain/URL registry.
-// Consumers import from "@spacefast/common/config".
+// Consumers import the domain/URL registry from "@spacefast/common/config".
 export * from "./domains.js";

package/dist/contracts/abuse.js

@@ -4,20 +4,13 @@ export const abuseReportCategorySchema = z
     .enum(["malware", "phishing", "spam", "copyright", "illegal_content", "other"])
     .describe("Reported abuse category.");
 export const abuseReportCreateSchema = z.object({
-    url: z.string().url().describe("Full URL of the content being reported."),
+    url: z.string().url().describe("URL of the reported content."),
     category: abuseReportCategorySchema,
-    description: z
-        .string()
-        .trim()
-        .min(10)
-        .max(5000)
-        .describe("What the reporter saw; 10-5000 characters."),
+    description: z.string().trim().min(10).max(5000).describe("What the reporter saw."),
 });
 export const abuseReportStatusSchema = z
     .enum(["new", "reviewing", "actioned", "closed"])
     .describe("Triage status of the report.");
-// Triage state machine: reports move forward through review; `closed` reports
-// can be reopened into `reviewing` (and only there) when new evidence lands.
 export const ABUSE_REPORT_STATUS_TRANSITIONS = {
     new: ["reviewing", "actioned", "closed"],
     reviewing: ["actioned", "closed"],
@@ -29,33 +22,25 @@ export const abuseReportSchema = z.object({
     status: abuseReportStatusSchema,
     category: abuseReportCategorySchema,
     url: z.string().describe("Reported URL."),
-    spaceId: z
-        .string()
-        .nullable()
-        .describe("Space the reported hostname resolved to, when resolution succeeds."),
+    spaceId: z.string().nullable().describe("Space the reported hostname resolved to."),
     createdAt: z.string().datetime().describe("When the report was filed."),
 });
-// Operator triage view: includes intake details the public receipt omits.
+// Intake details the public receipt omits.
 export const superadminAbuseReportSchema = abuseReportSchema.extend({
-    hostname: z.string().describe("Normalized hostname extracted from the reported URL."),
-    tenantId: z.string().nullable().describe("Tenant owning the resolved space, when resolved."),
+    hostname: z.string().describe("Normalized hostname from the reported URL."),
+    tenantId: z.string().nullable().describe("Tenant owning the resolved space."),
     description: z.string().describe("Reporter-supplied description."),
     updatedAt: z.string().datetime().describe("Last triage update."),
 });
 export const superadminAbuseReportListQuerySchema = cursorListQuerySchema.extend({
-    status: abuseReportStatusSchema.optional().describe("Filter the triage list by status."),
-    spaceId: z
-        .string()
-        .trim()
-        .min(1)
-        .optional()
-        .describe("Filter to reports that resolved to one Space."),
+    status: abuseReportStatusSchema.optional().describe("Filter by status."),
+    spaceId: z.string().trim().min(1).optional().describe("Filter to reports for this Space."),
     hostname: z
         .string()
         .trim()
         .min(1)
         .optional()
-        .describe("Filter by the normalized reported hostname; matching is case-insensitive."),
+        .describe("Filter by normalized hostname, case-insensitively."),
 });
 export const superadminAbuseReportPatchSchema = z.object({
     status: abuseReportStatusSchema.describe("New triage status; must be a valid transition from the current status."),

package/dist/contracts/access-profiles.d.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+/**
+ * The scopes any interactive authorization may grant — THE list every surface
+ * derives from. The device approval page, OAuth consent, the CLI receipt, and
+ * the server's approval validator all import this instead of keeping copies.
+ *
+ * This is the shared API set — NOT the granular `spaces:publish` /
+ * `builds:trigger` scopes, whose actions `publish:write` already covers. A
+ * person approving a device never sees two checkboxes that mean the same grant,
+ * and this set equals the hosted-MCP resource's scopes so the two converge.
+ */
+export declare const APPROVABLE_SCOPES: readonly ["teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write"];
+export type ApprovableScope = (typeof APPROVABLE_SCOPES)[number];
+/**
+ * Whether a scope, when approved, is bounded by the holder's team role. This is
+ * DERIVED from `isTenantAdmissionAction` — the same declaration the credential
+ * compiler mints from — so it can never disagree with what actually gets minted:
+ *
+ * - "team": grants at least one team-role action — authority OVER a team's
+ *   resources, bounded by the approver's LIVE role there on every request.
+ * - "account": every action is tenant-admission (never role-bounded), so no
+ *   team role gates it and any member can approve it (creating a
+ *   not-yet-existing team).
+ *
+ * Drives grantability (`scopeGrantableByRole`); the compiler owns the resource.
+ */
+export type ScopePlane = "team" | "account";
+export declare const SCOPE_PLANES: Record<ApprovableScope, ScopePlane>;
+export declare const ACCESS_PROFILE_IDS: readonly ["read", "agent"];
+export type AccessProfileId = (typeof ACCESS_PROFILE_IDS)[number];
+export declare const AccessProfileIdSchema: z.ZodEnum<{
+    read: "read";
+    agent: "agent";
+}>;
+export type AccessProfile = Readonly<{
+    id: AccessProfileId;
+    /** The ONE name every surface prints: CLI request line and receipt, approval
+     * page heading, consent screen, ledger row, email. */
+    label: string;
+    /** One sentence a person reads INSTEAD of the scope list. Reviewed copy —
+     * the derived scope list under it stays authoritative, so this can only ever
+     * be stale, never wrong about what is granted. */
+    blurb: string;
+    /** The negative space: notable things this profile deliberately can't do,
+     * shown under the blurb. Optional — omit when there's nothing worth calling
+     * out (a read-only profile speaks for itself). */
+    limits?: string;
+    scopes: readonly ApprovableScope[];
+}>;
+/**
+ * Named grant profiles. A profile is REQUEST INTENT — one word on device start
+ * with a server-owned meaning — never authority. Scopes are the grant
+ * vocabulary; actions are authority. The default is deliberately the full
+ * approvable set, matching what a `vercel login`/`gh auth login` grants:
+ * everything the credential's holder can do, capped per team by their live
+ * role at request time.
+ */
+export declare const ACCESS_PROFILES: {
+    readonly read: {
+        readonly id: "read";
+        readonly label: "Read-only access";
+        readonly blurb: "Read your teams, sites, and domains. Changes nothing.";
+        readonly scopes: readonly ["teams:read", "spaces:read", "domains:read"];
+    };
+    readonly agent: {
+        readonly id: "agent";
+        readonly label: "Agent access";
+        readonly blurb: "Create and publish sites, manage domains and DNS, create teams, and use Spacefast tools.";
+        readonly limits: "It can't delete sites, manage team members, change billing, or mint credentials.";
+        readonly scopes: readonly ["teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write"];
+    };
+};
+export declare const DEFAULT_ACCESS_PROFILE_ID: AccessProfileId;
+/** Parse an untyped scope list (wire, storage) into approvable scopes, in
+ * checklist order, deduplicated. Unknown entries grant nothing and are dropped. */
+export declare function approvableScopesFrom(scopes: readonly string[] | null | undefined): ApprovableScope[];
+/** The profile a scope set IS — exact set equality — or null once edited.
+ * Profiles are pinned distinct by test, so this inverse is total. */
+export declare function accessProfileForScopes(scopes: readonly string[] | null | undefined): AccessProfile | null;
+/**
+ * What every surface prints for a granted scope set: a profile's label, or
+ * `Custom (Agent access, minus …)` when the set is a strict subset of a
+ * profile, or plain `Custom`. Derived, never stored — a profile redefinition
+ * can never make an old receipt lie about its scopes.
+ */
+export declare function accessGrantLabel(scopes: readonly string[] | null | undefined, scopeLabel?: (scope: ApprovableScope) => string): string;

package/dist/contracts/access-profiles.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { OAUTH_SHARED_API_RESOURCE_SCOPES } from "./oauth-resources.js";
+import { isTenantAdmissionAction, oauthScopeActions } from "./oauth-scope-actions.js";
+/**
+ * The scopes any interactive authorization may grant — THE list every surface
+ * derives from. The device approval page, OAuth consent, the CLI receipt, and
+ * the server's approval validator all import this instead of keeping copies.
+ *
+ * This is the shared API set — NOT the granular `spaces:publish` /
+ * `builds:trigger` scopes, whose actions `publish:write` already covers. A
+ * person approving a device never sees two checkboxes that mean the same grant,
+ * and this set equals the hosted-MCP resource's scopes so the two converge.
+ */
+export const APPROVABLE_SCOPES = [...OAUTH_SHARED_API_RESOURCE_SCOPES];
+export const SCOPE_PLANES = 
+// SAFETY: mapped over every APPROVABLE_SCOPES entry, so the record is total.
+Object.fromEntries(APPROVABLE_SCOPES.map((scope) => [
+    scope,
+    oauthScopeActions([scope]).every(isTenantAdmissionAction) ? "account" : "team",
+]));
+export const ACCESS_PROFILE_IDS = ["read", "agent"];
+export const AccessProfileIdSchema = z.enum(ACCESS_PROFILE_IDS);
+/**
+ * Named grant profiles. A profile is REQUEST INTENT — one word on device start
+ * with a server-owned meaning — never authority. Scopes are the grant
+ * vocabulary; actions are authority. The default is deliberately the full
+ * approvable set, matching what a `vercel login`/`gh auth login` grants:
+ * everything the credential's holder can do, capped per team by their live
+ * role at request time.
+ */
+export const ACCESS_PROFILES = {
+    // Read-only. It can open a hosted MCP session and invoke tools (each tool call
+    // is re-gated by its own API scope, so only reads succeed), and it can observe
+    // the MCP console. It cannot MANAGE the console — closing sessions and
+    // approving paused executions are gated on `spaces:write` (see mcp/service.ts)
+    // — so it still changes nothing.
+    read: {
+        id: "read",
+        label: "Read-only access",
+        blurb: "Read your teams, sites, and domains. Changes nothing.",
+        scopes: ["teams:read", "spaces:read", "domains:read"],
+    },
+    agent: {
+        id: "agent",
+        label: "Agent access",
+        blurb: "Create and publish sites, manage domains and DNS, create teams, and use Spacefast tools.",
+        limits: "It can't delete sites, manage team members, change billing, or mint credentials.",
+        scopes: [...APPROVABLE_SCOPES],
+    },
+};
+export const DEFAULT_ACCESS_PROFILE_ID = "agent";
+function isApprovableScope(scope) {
+    return APPROVABLE_SCOPES.some((known) => known === scope);
+}
+/** Parse an untyped scope list (wire, storage) into approvable scopes, in
+ * checklist order, deduplicated. Unknown entries grant nothing and are dropped. */
+export function approvableScopesFrom(scopes) {
+    const requested = new Set(scopes ?? []);
+    return APPROVABLE_SCOPES.filter((scope) => requested.has(scope));
+}
+/** The profile a scope set IS — exact set equality — or null once edited.
+ * Profiles are pinned distinct by test, so this inverse is total. */
+export function accessProfileForScopes(scopes) {
+    const granted = new Set(approvableScopesFrom(scopes));
+    return (Object.values(ACCESS_PROFILES).find((profile) => profile.scopes.length === granted.size &&
+        profile.scopes.every((scope) => granted.has(scope))) ?? null);
+}
+/**
+ * What every surface prints for a granted scope set: a profile's label, or
+ * `Custom (Agent access, minus …)` when the set is a strict subset of a
+ * profile, or plain `Custom`. Derived, never stored — a profile redefinition
+ * can never make an old receipt lie about its scopes.
+ */
+export function accessGrantLabel(scopes, scopeLabel = (scope) => scope) {
+    const granted = approvableScopesFrom(scopes);
+    const exact = accessProfileForScopes(granted);
+    if (exact) {
+        return exact.label;
+    }
+    const grantedSet = new Set(granted);
+    // Narrowest containing profile names the diff; `read` precedes `agent`.
+    const profiles = Object.values(ACCESS_PROFILES);
+    const superset = profiles.find((profile) => granted.length > 0 && granted.every((scope) => profile.scopes.includes(scope)));
+    if (!superset) {
+        return "Custom";
+    }
+    const missing = superset.scopes.filter((scope) => !grantedSet.has(scope));
+    return `Custom (${superset.label}, minus ${missing.map((scope) => scopeLabel(scope)).join(", ")})`;
+}

package/dist/contracts/access.d.ts

@@ -10,16 +10,14 @@ export declare const spaceAccessPresetSchema: z.ZodEnum<{
 export type SpaceAccessPreset = z.infer<typeof spaceAccessPresetSchema>;
 /**
  * The sharing vocabulary. Capabilities are the ground truth; a role is a named
- * set of them, ordered from least to most. This is the only role enum and the
- * only role⇄capability mapping in the product — every surface (dashboard, CLI,
- * API, comments) names access with these four words and derives capabilities
- * here rather than keeping its own preset list.
+ * set of them, ordered from least to most. This is the product's only role enum
+ * and role⇄capability mapping: every surface derives its capabilities here.
  */
 export declare const ACCESS_ROLES: readonly ["viewer", "commenter", "editor", "manager"];
 export declare const accessRoleSchema: z.ZodEnum<{
+    editor: "editor";
     viewer: "viewer";
     commenter: "commenter";
-    editor: "editor";
     manager: "manager";
 }>;
 export type AccessRole = z.infer<typeof accessRoleSchema>;
@@ -31,15 +29,13 @@ export declare const ACCESS_ROLE_CAPABILITIES: {
 };
 export declare function accessRoleCapabilities(role: AccessRole): GrantCapability[];
 /**
- * The role a capability set amounts to, named by the strongest capability it
- * carries. A Grant assembled capability-by-capability need not match a role
- * exactly; this reports the role it reaches, never more.
+ * The role a capability set amounts to: the strongest role it reaches, never
+ * more. A Grant assembled capability-by-capability need not match one exactly.
  */
 export declare function accessRoleForCapabilities(capabilities: readonly GrantCapability[]): AccessRole;
 /**
- * Roles a credential-backed audience can carry. A Link or a password is a
- * secret anyone can forward, so it never publishes and never manages access —
- * the same boundary `grantSchema` enforces on the capabilities themselves.
+ * Roles a forwardable secret (a Link, a password) can carry. It never publishes
+ * and never manages access; `grantSchema` enforces that on capabilities too.
  */
 export declare const VISITOR_ACCESS_ROLES: readonly ["viewer", "commenter"];
 export type VisitorAccessRole = (typeof VISITOR_ACCESS_ROLES)[number];
@@ -70,18 +66,17 @@ export declare function accountPrincipal(userId: string): AccountPrincipal;
 /** The user id behind an account principal; null for anonymous or malformed. */
 export declare function accountPrincipalUserId(principal: string | undefined | null): string | null;
 /**
- * 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.
+ * The identity an authority reference names on its own, if any. The ONE place a
+ * class maps to an identity: at the exchange that authenticated it, never after.
  */
 export declare function principalForAuthority(reference: AuthorityReference): IdentifiedPrincipal | undefined;
 export declare const personGrantSchema: z.ZodObject<{
     id: z.ZodString;
     scope: z.ZodString;
     role: z.ZodEnum<{
+        editor: "editor";
         viewer: "viewer";
         commenter: "commenter";
-        editor: "editor";
         manager: "manager";
     }>;
     target: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -120,9 +115,9 @@ export declare const spacePersonSchema: z.ZodObject<{
         id: z.ZodString;
         scope: z.ZodString;
         role: z.ZodEnum<{
+            editor: "editor";
             viewer: "viewer";
             commenter: "commenter";
-            editor: "editor";
             manager: "manager";
         }>;
         target: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -175,9 +170,9 @@ export declare const spacePeopleListSchema: z.ZodObject<{
             id: z.ZodString;
             scope: z.ZodString;
             role: z.ZodEnum<{
+                editor: "editor";
                 viewer: "viewer";
                 commenter: "commenter";
-                editor: "editor";
                 manager: "manager";
             }>;
             target: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -373,9 +368,9 @@ export declare const canonicalAccessRequestStatusSchema: z.ZodEnum<{
     denied: "denied";
 }>;
 export declare const accessRequestRoleSchema: z.ZodEnum<{
+    editor: "editor";
     viewer: "viewer";
     commenter: "commenter";
-    editor: "editor";
     manager: "manager";
 }>;
 export type AccessRequestRole = z.infer<typeof accessRequestRoleSchema>;
@@ -386,9 +381,9 @@ export declare const canonicalAccessRequestSchema: z.ZodObject<{
     email: z.ZodString;
     scope: z.ZodString;
     requestedRole: z.ZodEnum<{
+        editor: "editor";
         viewer: "viewer";
         commenter: "commenter";
-        editor: "editor";
         manager: "manager";
     }>;
     message: z.ZodNullable<z.ZodString>;
@@ -424,9 +419,9 @@ export type LinkCapabilities = z.infer<typeof linkCapabilitiesSchema>;
 export declare const personGrantWriteSchema: z.ZodObject<{
     scope: z.ZodString;
     role: z.ZodEnum<{
+        editor: "editor";
         viewer: "viewer";
         commenter: "commenter";
-        editor: "editor";
         manager: "manager";
     }>;
     target: z.ZodDefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -446,9 +441,9 @@ export declare const spacePersonInviteWriteSchema: z.ZodObject<{
     grants: z.ZodArray<z.ZodObject<{
         scope: z.ZodString;
         role: z.ZodEnum<{
+            editor: "editor";
             viewer: "viewer";
             commenter: "commenter";
-            editor: "editor";
             manager: "manager";
         }>;
         target: z.ZodDefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -469,9 +464,9 @@ export declare const spacePersonGrantSetWriteSchema: z.ZodObject<{
     grants: z.ZodArray<z.ZodObject<{
         scope: z.ZodString;
         role: z.ZodEnum<{
+            editor: "editor";
             viewer: "viewer";
             commenter: "commenter";
-            editor: "editor";
             manager: "manager";
         }>;
         target: z.ZodDefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -564,9 +559,9 @@ export declare const canonicalAccessRequestCreateSchema: z.ZodObject<{
     email: z.ZodString;
     scope: z.ZodString;
     requestedRole: z.ZodDefault<z.ZodEnum<{
+        editor: "editor";
         viewer: "viewer";
         commenter: "commenter";
-        editor: "editor";
         manager: "manager";
     }>>;
     message: z.ZodOptional<z.ZodString>;
@@ -574,9 +569,9 @@ export declare const canonicalAccessRequestCreateSchema: z.ZodObject<{
 export declare const canonicalAccessRequestApproveSchema: z.ZodObject<{
     scope: z.ZodOptional<z.ZodString>;
     role: z.ZodOptional<z.ZodEnum<{
+        editor: "editor";
         viewer: "viewer";
         commenter: "commenter";
-        editor: "editor";
         manager: "manager";
     }>>;
 }, z.core.$strip>;
@@ -631,9 +626,8 @@ export declare const teamSpaceAccessDefaultWriteSchema: z.ZodObject<{
 export declare const ACCESS_TOKEN_KID = "spacefast-runtime-v1";
 export declare const ACCESS_TOKEN_ALG = "EdDSA";
 /**
- * The claim-schema version every platform token carries in `v`. One signer,
- * one claim contract: a verifier that understands v1 refuses a token minted
- * under a later shape instead of reading unknown claims optimistically.
+ * The claim-schema version every platform token carries in `v`. A verifier that
+ * understands v1 refuses a token minted under a later shape.
  */
 export declare const PLATFORM_TOKEN_CLAIM_VERSION: 1;
 export declare const BLOB_GATE_DOWNLOAD_TTL_SECONDS: number;