@spacefast/common 0.2.1 → 0.4.1

package/dist/agents/marketplace-prompts.d.ts

@@ -0,0 +1 @@
+export declare const AGENT_MARKETPLACE_DEFAULT_PROMPTS: readonly ["Publish this project with Spacefast and return its live and immutable URLs.", "Show the latest deployments for my Spacefast Space.", "Show the DNS and SSL status for my Spacefast Space."];

package/dist/agents/marketplace-prompts.js

@@ -0,0 +1,6 @@
+import { AGENT_DISTRIBUTION_PROFILE } from "./registry/core.js";
+export const AGENT_MARKETPLACE_DEFAULT_PROMPTS = [
+    `Publish this project with ${AGENT_DISTRIBUTION_PROFILE.displayName} and return its live and immutable URLs.`,
+    `Show the latest deployments for my ${AGENT_DISTRIBUTION_PROFILE.displayName} Space.`,
+    `Show the DNS and SSL status for my ${AGENT_DISTRIBUTION_PROFILE.displayName} Space.`,
+];

package/dist/agents/registry/core.d.ts

@@ -66,13 +66,10 @@ export type RegistryContext = Readonly<{
     wwwOrigin: string;
 }>;
 /**
- * `declared` is what a hand-entered registry row can honestly claim: a human
- * read the vendor source on `checkedAt`. Only the scheduled deeplink probe
- * (scripts/marketplaces/probe-deeplinks.mjs) may write `probed` or `failed`, and
- * a `failed` deeplink is demoted out of `interactive-primary` automatically.
- * There is deliberately no "verified" value: nothing in this file can earn it.
+ * `declared` means a human read the vendor source on `checkedAt`.
+ * Registry entries do not claim that the integration has been tested.
  */
-export type RegistryVerificationStatus = "declared" | "probed" | "failed";
+export type RegistryVerificationStatus = "declared";
 export type RegistryVerification = Readonly<{
     checkedAt: string;
     evidence?: string;
@@ -194,7 +191,7 @@ export type AgentEntry = Readonly<{
     tier: "featured" | "listed";
     verification: RegistryVerification;
     vendor: string;
-    wizardGroup: "claude" | "openai" | "coding-agents" | "personal-agents" | "mcp-apps" | "prompt-first" | null;
+    wizardGroup: "claude" | "openai" | "coding-agents" | "personal-agents" | "prompt-first" | null;
 }>;
 export type PresentedMethod = Readonly<{
     /**
@@ -274,11 +271,6 @@ export declare function hostedMcpServersConfig(context: RegistryContext): string
 export declare const AGENT_REGISTRY: readonly AgentEntry[];
 export declare function getAgentEntry(id: AgentId): AgentEntry;
 export declare function resolveAgentId(value: string): AgentId | null;
-/**
- * The ranking rule, as a pure function so the demote path is testable without a
- * registry entry: a deeplink whose last probe failed is dropped from the
- * interactive lane, and everything else sorts by its per-context rank.
- */
 export declare function methodsForContext(methods: readonly IntegrationMethod[], context: PresentationContext): readonly IntegrationMethod[];
 export declare function agentMethodsForContext(agentId: AgentId, context: PresentationContext): readonly IntegrationMethod[];
 /**

package/dist/agents/registry/core.js

@@ -5,7 +5,6 @@
  * reads. Runtime-specific path and config mechanics live in ./node.ts.
  */
 import { serviceOrigin } from "../../config/domains.js";
-import { DEEPLINK_PROBE_RESULTS } from "./deeplink-probes.js";
 export const AGENT_IDS = [
     "claude-code",
     "claude-app",
@@ -523,10 +522,7 @@ function jsonHostedConfig(root) {
     }, null, 2);
 }
 /**
- * Applies the two invariants a hand-written method array cannot hold on its own:
- * every deeplink's declared fallback resolves to a sibling method (and takes that
- * sibling's real kind), and any probe result recorded for a deeplink overrides
- * its `declared` verification status.
+ * Resolve every deeplink's fallback to a sibling method and its actual kind.
  */
 function resolveMethods(agentId, methods) {
     return methods.map((method) => {
@@ -536,18 +532,9 @@ function resolveMethods(agentId, methods) {
         if (!target || target === method) {
             throw new TypeError(`Agent ${agentId} deeplink "${method.id}" declares fallback "${method.fallback.id}", which is not one of its methods.`);
         }
-        const probe = DEEPLINK_PROBE_RESULTS[`${agentId}:${method.id}`];
-        const probed = { ...method.verification };
-        if (probe) {
-            probed.checkedAt = probe.checkedAt;
-            probed.status = probe.status;
-            if (probe.evidence !== undefined)
-                probed.evidence = probe.evidence;
-        }
         return {
             ...method,
             fallback: { id: target.id, kind: target.kind },
-            verification: probed,
         };
     });
 }
@@ -887,7 +874,7 @@ export const AGENT_REGISTRY = [
         detectionHints: [],
         kind: "chat-app",
         tier: "listed",
-        wizardGroup: "mcp-apps",
+        wizardGroup: "coding-agents",
         capabilities: ["skills", "mcp-oauth"],
         skills: { agentsDirs: true, claudeDirs: false },
         agentsMd: "native",
@@ -1046,7 +1033,7 @@ export const AGENT_REGISTRY = [
         detectionHints: [".factory"],
         kind: "coding-agent",
         tier: "listed",
-        wizardGroup: "coding-agents",
+        wizardGroup: null,
         capabilities: ["skills", "mcp-local", "mcp-oauth", "plugin"],
         skills: { agentsDirs: true, claudeDirs: true },
         agentsMd: "native",
@@ -1079,7 +1066,7 @@ export const AGENT_REGISTRY = [
         detectionHints: [".cline"],
         kind: "editor",
         tier: "listed",
-        wizardGroup: "coding-agents",
+        wizardGroup: null,
         capabilities: ["skills", "mcp-oauth", "plugin"],
         skills: { agentsDirs: true, claudeDirs: true },
         agentsMd: "native",
@@ -1102,7 +1089,7 @@ export const AGENT_REGISTRY = [
         detectionHints: [".continue"],
         kind: "editor",
         tier: "listed",
-        wizardGroup: "prompt-first",
+        wizardGroup: null,
         capabilities: ["skills"],
         skills: { agentsDirs: false, claudeDirs: true },
         agentsMd: "none",
@@ -1127,7 +1114,7 @@ export const AGENT_REGISTRY = [
         detectionHints: [],
         kind: "mcp-app",
         tier: "listed",
-        wizardGroup: "mcp-apps",
+        wizardGroup: "personal-agents",
         capabilities: ["mcp-oauth", "deeplink-only"],
         skills: { agentsDirs: false, claudeDirs: false },
         agentsMd: "none",
@@ -1206,7 +1193,7 @@ export const AGENT_REGISTRY = [
         detectionHints: [],
         kind: "mcp-app",
         tier: "listed",
-        wizardGroup: "mcp-apps",
+        wizardGroup: "personal-agents",
         capabilities: ["mcp-oauth", "deeplink-only"],
         skills: { agentsDirs: false, claudeDirs: false },
         agentsMd: "none",
@@ -1283,17 +1270,9 @@ export function getAgentEntry(id) {
 export function resolveAgentId(value) {
     return idByAlias.get(normalizeLookup(value)) ?? null;
 }
-/**
- * The ranking rule, as a pure function so the demote path is testable without a
- * registry entry: a deeplink whose last probe failed is dropped from the
- * interactive lane, and everything else sorts by its per-context rank.
- */
 export function methodsForContext(methods, context) {
     return methods
         .filter((method) => method.rank[context] !== undefined)
-        .filter((method) => method.kind !== "deeplink" ||
-        method.verification.status !== "failed" ||
-        context !== "interactive-primary")
         .toSorted((left, right) => (left.rank[context] ?? 0) - (right.rank[context] ?? 0));
 }
 export function agentMethodsForContext(agentId, context) {

package/dist/config/domains.d.ts

@@ -17,17 +17,19 @@ 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";
+export declare const STAGING_ENV_DOMAIN: "staging.spacefast.com";
 /**
- * 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 two environments the deploy lanes ship to, keyed by the name each one
+ * carries everywhere else: the tag 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.
+ * from `DeployEnv` above, which names the local stacks beside prod. `dev` is
+ * only a local stack name now; the hosted dev environment is retired.
  */
-export type HostedEnv = "dev" | "staging" | "prod";
-export declare const HOSTED_ENV_DOMAINS: Readonly<Record<HostedEnv, string>>;
+export type HostedEnv = "staging" | "prod";
+export declare const HOSTED_ENV_DOMAINS: {
+    readonly staging: "staging.spacefast.com";
+    readonly prod: "spacefast.com";
+};
 /**
  * The hosted environment a `SPACEFAST_ENV` value names, or null. `production`
  * is accepted for `prod`: it is what the running services already carry, and

package/dist/config/domains.js

@@ -8,11 +8,8 @@ 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 STAGING_ENV_DOMAIN = "staging.spacefast.com";
 export const HOSTED_ENV_DOMAINS = {
-    dev: DEV_DEPLOY_ENV_DOMAIN,
     staging: STAGING_ENV_DOMAIN,
     prod: PROD_ENV_DOMAIN,
 };
@@ -56,7 +53,7 @@ export function envDomainsFor(domain) {
             superadmin: `superadmin.${domain}`,
             cast: `cast.${domain}`,
             mcp: `mcp.${domain}`,
-            push: prod ? "push.new" : `push.${domain}`,
+            push: prod ? `git.${domain}` : `push.${domain}`,
             fieldguide: prod ? "pitch.view.fast" : `fieldguide.${domain}`,
         },
     };
@@ -117,8 +114,8 @@ export function resolveViewFastApex(environment) {
     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.
+    // NODE_ENV is production. `dev` is the local stack's name, and a local stack
+    // must keep the local apex rather than allocate under a hosted namespace.
     const nodeEnvironment = environment.NODE_ENV?.trim().toLowerCase();
     if (!["prod", "production"].includes(nodeEnvironment ?? ""))
         return DEV_VIEW_FAST_APEX;

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

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import type { GrantCapability } from "./grants-core.js";
+/** Media type of the handoff document that carries a session to the runtime. */
+export declare const ACCESS_HANDOFF_MEDIA_TYPE = "application/vnd.spacefast.access-handoff+json";
+/**
+ * The sharing vocabulary. Capabilities are the ground truth; a role is a named
+ * 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";
+    manager: "manager";
+}>;
+export type AccessRole = z.infer<typeof accessRoleSchema>;
+export declare const ACCESS_ROLE_CAPABILITIES: {
+    readonly viewer: readonly ["page.view"];
+    readonly commenter: readonly ["page.view", "comments.read", "comments.write"];
+    readonly editor: readonly ["page.view", "comments.read", "comments.write", "content.publish"];
+    readonly manager: readonly ["page.view", "comments.read", "comments.write", "content.publish", "access.manage"];
+};
+export declare function accessRoleCapabilities(role: AccessRole): GrantCapability[];
+/**
+ * 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 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];
+export declare function accessRoleRank(role: AccessRole): number;
+export declare function maxAccessRole(left: AccessRole | null, right: AccessRole | null): AccessRole | null;
+/**
+ * Canonicalizes the URL route identity used by People, Links, requests,
+ * comments, and runtime authorization.
+ */
+export declare function normalizeAccessScopePath(input: string): string;
+export declare const accessScopePathSchema: z.ZodString;
+export type AccessScopePath = z.infer<typeof accessScopePathSchema>;
+export declare function accessScopeContains(scope: string, path: string): boolean;
+export declare const authorityReferenceSchema: z.ZodString;
+export type AuthorityReference = z.infer<typeof authorityReferenceSchema>;
+export declare const accountPrincipalSchema: z.ZodString;
+export type AccountPrincipal = z.infer<typeof accountPrincipalSchema>;
+export declare const identifiedPrincipalSchema: z.ZodString;
+export type IdentifiedPrincipal = z.infer<typeof identifiedPrincipalSchema>;
+export declare const accessPrincipalSchema: z.ZodUnion<readonly [z.ZodLiteral<"anonymous">, z.ZodString]>;
+export type AccessPrincipal = z.infer<typeof accessPrincipalSchema>;
+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. 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 ACCESS_TOKEN_KID = "spacefast-runtime-v1";
+export declare const ACCESS_TOKEN_ALG = "EdDSA";
+/**
+ * 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;
+/**
+ * How long an embedded version preview keeps working before the dashboard has
+ * to mint again. Same budget as a file link: the credential rides a URL, and a
+ * URL-borne credential is only safe while it rots quickly. The runtime sizes
+ * the cookie it echoes this token into from the same expiry, so the preview and
+ * its subresources die together instead of the page outliving its assets.
+ */
+export declare const VERSION_PREVIEW_SESSION_TTL_SECONDS: number;
+export declare const BLOB_GATE_SCAN_TTL_SECONDS: number;
+export declare const BLOB_GATE_UPLOAD_TTL_SECONDS: number;
+export declare const RUNTIME_JWKS_WELL_KNOWN_FILENAME = "spacefast-runtime-jwks.json";
+export declare const accessTokenPublicProfileSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    username: z.ZodOptional<z.ZodString>;
+    avatar_url: z.ZodOptional<z.ZodURL>;
+}, z.core.$strict>;
+export type AccessTokenPublicProfile = z.infer<typeof accessTokenPublicProfileSchema>;
+export declare const accessTokenPayloadSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    sub: z.ZodString;
+    principal: z.ZodOptional<z.ZodString>;
+    authorities: z.ZodArray<z.ZodString>;
+    exp: z.ZodNumber;
+    nbf: z.ZodNumber;
+    iat: z.ZodNumber;
+    iss: z.ZodString;
+    aud: z.ZodString;
+    host: z.ZodString;
+    spaceId: z.ZodString;
+    sid: z.ZodString;
+    generation: z.ZodNumber;
+    emailVerified: z.ZodDefault<z.ZodBoolean>;
+    profile: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+        avatar_url: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strict>>;
+    jti: z.ZodString;
+    purpose: z.ZodLiteral<"handoff">;
+    browserState: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AccessTokenPayload = z.infer<typeof accessTokenPayloadSchema>;
+export declare const runtimeBearerTokenPayloadSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    sub: z.ZodString;
+    principal: z.ZodOptional<z.ZodString>;
+    authorities: z.ZodArray<z.ZodString>;
+    exp: z.ZodNumber;
+    nbf: z.ZodNumber;
+    iat: z.ZodNumber;
+    iss: z.ZodString;
+    aud: z.ZodString;
+    host: z.ZodString;
+    spaceId: z.ZodString;
+    sid: z.ZodString;
+    generation: z.ZodNumber;
+    emailVerified: z.ZodDefault<z.ZodBoolean>;
+    profile: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+        avatar_url: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strict>>;
+    jti: z.ZodString;
+    purpose: z.ZodLiteral<"runtime-bearer">;
+}, z.core.$strip>;
+export type RuntimeBearerTokenPayload = z.infer<typeof runtimeBearerTokenPayloadSchema>;

package/dist/contracts/access-core.js

@@ -0,0 +1,242 @@
+import { z } from "zod";
+// The access VOCABULARY a serving runtime needs to answer a request: what a role
+// means in capabilities, how a URL scope is canonicalized, who a session is, and
+// the shape of the handoff token that says so.
+//
+// Spacefast's directory of people, Links, access requests and team defaults —
+// the records BEHIND those sessions — is the host's own and lives in `./access.js`.
+/** Media type of the handoff document that carries a session to the runtime. */
+export const ACCESS_HANDOFF_MEDIA_TYPE = "application/vnd.spacefast.access-handoff+json";
+/**
+ * The sharing vocabulary. Capabilities are the ground truth; a role is a named
+ * 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 const ACCESS_ROLES = ["viewer", "commenter", "editor", "manager"];
+export const accessRoleSchema = z.enum(ACCESS_ROLES);
+export const ACCESS_ROLE_CAPABILITIES = {
+    viewer: ["page.view"],
+    commenter: ["page.view", "comments.read", "comments.write"],
+    editor: ["page.view", "comments.read", "comments.write", "content.publish"],
+    manager: ["page.view", "comments.read", "comments.write", "content.publish", "access.manage"],
+};
+export function accessRoleCapabilities(role) {
+    return [...ACCESS_ROLE_CAPABILITIES[role]];
+}
+/**
+ * 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 function accessRoleForCapabilities(capabilities) {
+    if (capabilities.includes("access.manage"))
+        return "manager";
+    if (capabilities.includes("content.publish"))
+        return "editor";
+    if (capabilities.includes("comments.write"))
+        return "commenter";
+    return "viewer";
+}
+/**
+ * Roles a forwardable secret (a Link, a password) can carry. It never publishes
+ * and never manages access; `grantSchema` enforces that on capabilities too.
+ */
+export const VISITOR_ACCESS_ROLES = [
+    "viewer",
+    "commenter",
+];
+export function accessRoleRank(role) {
+    return ACCESS_ROLES.indexOf(role);
+}
+export function maxAccessRole(left, right) {
+    if (left === null)
+        return right;
+    if (right === null)
+        return left;
+    return accessRoleRank(left) >= accessRoleRank(right) ? left : right;
+}
+function hasUnsafeScopeCharacter(value) {
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint === undefined ||
+            codePoint <= 0x1f ||
+            codePoint === 0x7f ||
+            character === "\\" ||
+            character === "?" ||
+            character === "#") {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Canonicalizes the URL route identity used by People, Links, requests,
+ * comments, and runtime authorization.
+ */
+export function normalizeAccessScopePath(input) {
+    const value = input;
+    if (!value.startsWith("/") || value.startsWith("//") || hasUnsafeScopeCharacter(value)) {
+        throw new TypeError("scope must be a plain absolute URL path");
+    }
+    let decoded;
+    try {
+        decoded = decodeURIComponent(value);
+    }
+    catch {
+        throw new TypeError("scope contains malformed percent encoding");
+    }
+    if (/%2f|%5c/iu.test(value) || hasUnsafeScopeCharacter(decoded)) {
+        throw new TypeError("scope contains an ambiguous encoded separator");
+    }
+    const segments = [];
+    for (const rawSegment of decoded.split("/")) {
+        const segment = rawSegment.normalize("NFC");
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..") {
+            if (segments.length === 0) {
+                throw new TypeError("scope escapes the URL root");
+            }
+            segments.pop();
+            continue;
+        }
+        segments.push(segment);
+    }
+    if (segments.at(-1) === "index.html") {
+        segments.pop();
+    }
+    return segments.length === 0 ? "/" : `/${segments.join("/")}`;
+}
+export const accessScopePathSchema = z
+    .string()
+    .min(1)
+    .max(1024)
+    .check((context) => {
+    try {
+        context.value = normalizeAccessScopePath(context.value);
+    }
+    catch (error) {
+        context.issues.push({
+            code: "custom",
+            input: context.value,
+            message: error instanceof Error ? error.message : "invalid access scope",
+        });
+    }
+});
+export function accessScopeContains(scope, path) {
+    const canonicalScope = normalizeAccessScopePath(scope);
+    const canonicalPath = normalizeAccessScopePath(path);
+    return (canonicalScope === "/" ||
+        canonicalPath === canonicalScope ||
+        canonicalPath.startsWith(`${canonicalScope}/`));
+}
+export const authorityReferenceSchema = z
+    .string()
+    .regex(/^(member|person|link|password|machine|claim-preview|external):[A-Za-z0-9_.-]+$/);
+// WHO a session is, orthogonal to WHAT it may do. A session has exactly one
+// principal and any number of authorities; neither implies the other.
+export const accountPrincipalSchema = z.string().regex(/^account:[A-Za-z0-9_-]+$/);
+// `person:` is someone this Space invited by email and who accepted, a named
+// identity with no platform account behind it. `external:` is a subject an
+// identity connection vouched for. Every other authority class (Link, password,
+// machine, claim preview) authenticates no one and leaves the session anonymous.
+export const identifiedPrincipalSchema = z
+    .string()
+    .regex(/^(?:account|person|external):[A-Za-z0-9_.-]+$/);
+export const accessPrincipalSchema = z.union([z.literal("anonymous"), identifiedPrincipalSchema]);
+export function accountPrincipal(userId) {
+    return accountPrincipalSchema.parse(`account:${userId}`);
+}
+/** The user id behind an account principal; null for anonymous or malformed. */
+export function accountPrincipalUserId(principal) {
+    if (!principal || !accountPrincipalSchema.safeParse(principal).success)
+        return null;
+    return principal.slice("account:".length);
+}
+/**
+ * The 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 function principalForAuthority(reference) {
+    return reference.startsWith("person:") || reference.startsWith("external:")
+        ? identifiedPrincipalSchema.parse(reference)
+        : undefined;
+}
+// The platform token format: what a runtime verifies a handoff against.
+export const ACCESS_TOKEN_KID = "spacefast-runtime-v1";
+export const ACCESS_TOKEN_ALG = "EdDSA";
+/**
+ * The claim-schema version every platform token carries in `v`. A verifier that
+ * understands v1 refuses a token minted under a later shape.
+ */
+export const PLATFORM_TOKEN_CLAIM_VERSION = 1;
+export const BLOB_GATE_DOWNLOAD_TTL_SECONDS = 10 * 60;
+/**
+ * How long an embedded version preview keeps working before the dashboard has
+ * to mint again. Same budget as a file link: the credential rides a URL, and a
+ * URL-borne credential is only safe while it rots quickly. The runtime sizes
+ * the cookie it echoes this token into from the same expiry, so the preview and
+ * its subresources die together instead of the page outliving its assets.
+ */
+export const VERSION_PREVIEW_SESSION_TTL_SECONDS = 10 * 60;
+export const BLOB_GATE_SCAN_TTL_SECONDS = 60 * 60;
+export const BLOB_GATE_UPLOAD_TTL_SECONDS = 60 * 60;
+export const RUNTIME_JWKS_WELL_KNOWN_FILENAME = "spacefast-runtime-jwks.json";
+// Public identity, attached only when a consumer must render the person behind
+// an authority. The minting side normalizes a provider avatar or derives one
+// from the email, then drops the email. Raw email and provider-private profile
+// metadata never belong here.
+export const accessTokenPublicProfileSchema = z
+    .object({
+    name: z.string().min(1).max(120).optional(),
+    username: z.string().min(1).max(160).optional(),
+    avatar_url: z
+        .url({ protocol: /^https?$/ })
+        .max(2_048)
+        .optional(),
+})
+    .strict();
+const authorityTokenPayloadClaimsSchema = z.object({
+    v: z.literal(PLATFORM_TOKEN_CLAIM_VERSION),
+    sub: authorityReferenceSchema,
+    // Who this handoff authenticated, when it authenticated anybody. Its absence
+    // means the runtime session is anonymous. Identity comes from here alone,
+    // never inferred from the authority classes below.
+    principal: identifiedPrincipalSchema.optional(),
+    authorities: z.array(authorityReferenceSchema).min(1).max(16),
+    exp: z.number().int().nonnegative(),
+    nbf: z.number().int().nonnegative(),
+    iat: z.number().int().nonnegative(),
+    iss: z.string().min(1),
+    // The Space this handoff belongs to. A Space keeps its id across claim,
+    // rename, and custom domains, so the audience is stable where a host is not.
+    aud: z.string().min(1),
+    // The lowercased serving host the handoff was minted for. The runtime rejects
+    // a token presented on any other host.
+    host: z.string().min(1),
+    spaceId: z.string().min(1),
+    // Shared opaque identity for the runtime request/session and its
+    // access-origin collaboration session. It never authorizes by itself.
+    sid: z.string().regex(/^[a-f0-9]{64}$/),
+    generation: z.number().int().nonnegative(),
+    emailVerified: z.boolean().default(false),
+    profile: accessTokenPublicProfileSchema.optional(),
+    jti: z.string().min(1),
+});
+export const accessTokenPayloadSchema = authorityTokenPayloadClaimsSchema.extend({
+    // Typed purpose from the one platform signer. The runtime REQUIRES exactly
+    // this value before consuming the jti, so no other purpose signed by the same
+    // key can redeem into a visitor session.
+    purpose: z.literal("handoff"),
+    // Present only when the runtime initiated an interactive browser login. The
+    // runtime compares it with its host-only HttpOnly cookie before consuming
+    // the handoff, so a copied callback cannot install a session elsewhere.
+    browserState: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/)
+        .optional(),
+});
+export const runtimeBearerTokenPayloadSchema = authorityTokenPayloadClaimsSchema.extend({
+    // A runtime bearer is reusable until expiry. It is deliberately a different
+    // purpose from a handoff, which the runtime consumes exactly once.
+    purpose: z.literal("runtime-bearer"),
+});

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

@@ -9,7 +9,7 @@ import { z } from "zod";
  * 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 declare const APPROVABLE_SCOPES: readonly ["teams:read", "teams:create", "teams:members.write", "spaces:read", "spaces:write", "spaces:rename", "spaces:delete", "versions:download", "publish:write", "domains:read", "domains:write", "connectors:read", "connectors:write", "connectors:execute"];
 export type ApprovableScope = (typeof APPROVABLE_SCOPES)[number];
 /**
  * Whether a scope, when approved, is bounded by the holder's team role. This is
@@ -50,10 +50,10 @@ export type AccessProfile = Readonly<{
 /**
  * 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.
+ * vocabulary; actions are authority. Agent access grants routine capabilities by
+ * default and leaves destructive Space deletion for explicit or temporary
+ * approval. Every capability remains capped per team by the approver's live role
+ * at request time.
  */
 export declare const ACCESS_PROFILES: {
     readonly read: {
@@ -65,9 +65,9 @@ export declare const ACCESS_PROFILES: {
     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"];
+        readonly blurb: "Create and publish sites. Manage domains and DNS. Invite team members, create teams, and use Spacefast tools.";
+        readonly limits: "It asks for temporary approval before it deletes sites. It can't remove team members, change their roles, change billing, or mint credentials.";
+        readonly scopes: readonly ("teams:read" | "teams:create" | "teams:members.write" | "spaces:read" | "spaces:write" | "spaces:rename" | "versions:download" | "publish:write" | "domains:read" | "domains:write" | "connectors:read" | "connectors:write" | "connectors:execute")[];
     };
 };
 export declare const DEFAULT_ACCESS_PROFILE_ID: AccessProfileId;