@spacefast/common 0.0.24 → 0.2.1

package/dist/config/domains.d.ts

@@ -1,13 +1,13 @@
 /** Deployment environment a URL is being built for. */
 export type DeployEnv = "dev" | "test" | "prod";
 /** Logical services that each get their own host. */
-export type Service = "www" | "api" | "dashboard" | "superadmin" | "cast" | "mcp" | "push" | "fieldguide";
+export type Service = "www" | "api" | "access" | "dashboard" | "superadmin" | "cast" | "mcp" | "push" | "fieldguide";
 export type EnvDomains = {
     /** Apex/base origin for the marketing site (the `www` service + bare apex). */
     readonly apex: string;
     /** Cookie domain that scopes auth across every subdomain of this env. */
     readonly cookieDomain: string;
-    /** Scheme used to build origins. SSL everywhere — even local (via portless). */
+    /** Scheme used to build origins. SSL everywhere, even local (via portless). */
     readonly protocol: "http" | "https";
     /** Fully-qualified hostname per service. */
     readonly hosts: Readonly<Record<Service, string>>;
@@ -16,18 +16,46 @@ export type EnvDomains = {
 export declare const PROD_ENV_DOMAIN: "spacefast.com";
 /** The local-dev apex (portless serves every subdomain over HTTPS). */
 export declare const DEV_ENV_DOMAIN: "sf.localhost";
+/** The deployed staging apex. Not local: staging is a hosted environment. */
+export declare const STAGING_ENV_DOMAIN: "stattic.net";
+/** The deployed dev apex. Local dev is separate and stays on sf.localhost. */
+export declare const DEV_DEPLOY_ENV_DOMAIN: "stattic.xyz";
 /**
- * Construct the full per-service host map from a single env domain
- * (`spacefast.com`, `sf.localhost`, …). One knob — services are always
- * `<service>.<domain>` over https, with two deliberate exceptions:
- * the marketing site sits on the bare prod apex, and the internal handbook
- * lives on the view.fast infra apex in prod.
+ * The three environments the deploy lanes ship to, keyed by the name each one
+ * carries everywhere else: the branch map in scripts/deploy-environment.mjs,
+ * the GitHub Environment, and `SPACEFAST_ENV` on the running service. Distinct
+ * from `DeployEnv` above, which names the local stacks beside prod.
+ */
+export type HostedEnv = "dev" | "staging" | "prod";
+export declare const HOSTED_ENV_DOMAINS: Readonly<Record<HostedEnv, string>>;
+/**
+ * The hosted environment a `SPACEFAST_ENV` value names, or null. `production`
+ * is accepted for `prod`: it is what the running services already carry, and
+ * what their alert routing and email tags key on.
+ */
+export declare function hostedEnvFor(environment: string | undefined): HostedEnv | null;
+/** The apex a hosted environment serves from, or null when the name is not one. */
+export declare function hostedEnvDomain(environment: string | undefined): string | null;
+/**
+ * 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 declare function envDomainsFor(domain: string): EnvDomains;
 /** Origin (scheme + host, no trailing slash) for a service in an environment. */
 export declare function serviceOrigin(service: Service, env: DeployEnv): string;
-/** 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 declare const DOCS_BASE_URL: string;
+/**
+ * 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 declare const DEFAULT_API_URL: string;
 /**
  * The production infrastructure apex. Committed artifacts and anything
  * customer- or agent-facing (OpenAPI examples, docs, skills) must show this
@@ -37,9 +65,48 @@ export declare const DOCS_BASE_URL: string;
 export declare const PROD_VIEW_FAST_APEX: "view.fast";
 /** The local-dev infrastructure apex. Never appears in committed artifacts. */
 export declare const DEV_VIEW_FAST_APEX: "preview.space";
-/** Resolve the infrastructure apex, allowing an explicit deployment override. */
-export declare function resolveViewFastApex(environment: Readonly<Partial<Pick<NodeJS.ProcessEnv, "NODE_ENV" | "SPACEFAST_VIEW_FAST_APEX">>>): string;
+/**
+ * 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 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: 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 declare function resolveViewFastApex(environment: Readonly<Partial<Pick<NodeJS.ProcessEnv, "NODE_ENV" | "SPACEFAST_ENV" | "SPACEFAST_VIEW_FAST_APEX">>>): string;
 /** Infrastructure apex used for public managed/custom domains. */
 export declare const VIEW_FAST_APEX: string;
-/** Reserved first-label prefix for the management namespace; users may not register it. */
-export declare const MANAGEMENT_LABEL_PREFIX: "wpc-manage-";
+/**
+ * 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 declare function resolveTestApex(environment: Readonly<Partial<Pick<NodeJS.ProcessEnv, "NODE_ENV" | "SPACEFAST_ENV" | "SPACEFAST_VIEW_FAST_APEX" | "SPACEFAST_TEST_APEX">>>): string;
+/** The resolved test-mode apex for this process. */
+export declare const TEST_APEX: string;
+export declare function testApexForTenant(tenantId: string, testApex?: string): string;
+/**
+ * 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 declare function isTestApexHostname(hostname: string, testApex?: string): boolean;

package/dist/config/domains.js

@@ -1,30 +1,57 @@
-// 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. 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,
+    staging: STAGING_ENV_DOMAIN,
+    prod: PROD_ENV_DOMAIN,
+};
+/**
+ * The hosted environment a `SPACEFAST_ENV` value names, or null. `production`
+ * is accepted for `prod`: it is what the running services already carry, and
+ * what their alert routing and email tags key on.
+ */
+export function hostedEnvFor(environment) {
+    if (!environment)
+        return null;
+    const normalized = environment.trim().toLowerCase();
+    if (normalized === "production")
+        return "prod";
+    return Object.hasOwn(HOSTED_ENV_DOMAINS, normalized) ? normalized : null;
+}
+/** The apex a hosted environment serves from, or null when the name is not one. */
+export function hostedEnvDomain(environment) {
+    const hosted = hostedEnvFor(environment);
+    return hosted ? HOSTED_ENV_DOMAINS[hosted] : null;
+}
 /**
- * Construct the full per-service host map from a single env domain
- * (`spacefast.com`, `sf.localhost`, …). One knob — services are always
- * `<service>.<domain>` over https, with two deliberate exceptions:
- * the marketing site sits on the bare prod apex, and the internal handbook
- * lives on the view.fast infra apex 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;
+    const hosted = Object.values(HOSTED_ENV_DOMAINS).some((hostedDomain) => hostedDomain === domain);
     return {
         apex: domain,
         cookieDomain: `.${domain}`,
         protocol: "https",
         hosts: {
-            www: prod ? domain : `www.${domain}`,
+            www: hosted ? domain : `www.${domain}`,
             api: `api.${domain}`,
+            access: `access.${domain}`,
             dashboard: `my.${domain}`,
             superadmin: `superadmin.${domain}`,
             cast: `cast.${domain}`,
@@ -35,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,
@@ -53,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
@@ -65,18 +98,84 @@ export const DOCS_BASE_URL = `${serviceOrigin("www", "prod")}/docs`;
 export const PROD_VIEW_FAST_APEX = "view.fast";
 /** The local-dev infrastructure apex. Never appears in committed artifacts. */
 export const DEV_VIEW_FAST_APEX = "preview.space";
-/** Resolve the infrastructure apex, allowing an explicit deployment override. */
+/**
+ * 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 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: 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. `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();
-    return (environment.SPACEFAST_VIEW_FAST_APEX?.trim().toLowerCase() ||
-        (["prod", "production"].includes(nodeEnvironment ?? "")
-            ? PROD_VIEW_FAST_APEX
-            : DEV_VIEW_FAST_APEX));
+    if (!["prod", "production"].includes(nodeEnvironment ?? ""))
+        return DEV_VIEW_FAST_APEX;
+    return hostedEnvFor(environment.SPACEFAST_ENV) === "prod"
+        ? PROD_VIEW_FAST_APEX
+        : DEV_VIEW_FAST_APEX;
 }
 /** 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(", ")})`;
+}