@spacefast/common 0.0.24 → 0.2.1

package/dist/contracts/internal.js

@@ -1,10 +1,5 @@
 import { z } from "zod";
 import { baseDiagnosticSchema } from "./common.js";
-export const conventionFilesSchema = z.object({
-    redirects: z.string().optional(),
-    headers: z.string().optional(),
-    routes: z.string().optional(),
-});
 const manifestSha256Schema = z
     .string()
     .regex(/^[0-9a-f]{64}$/, "sha256 must be 64 lowercase hex characters without a prefix.")
@@ -20,18 +15,13 @@ export const manifestFileSchema = z.object({
     size: z.number().int().nonnegative().describe("File size in bytes."),
     sha256: manifestSha256Schema
         .optional()
-        .describe("SHA-256 content digest: exactly 64 lowercase hex characters, no `sha256:` prefix (Version.manifestHash is the only prefixed form). Required when the caller uploads local bytes; may be absent on historical records and sourceUrl entries."),
+        .describe("Optional SHA-256 content digest, 64 lowercase hex characters without the `sha256:` prefix. Omit it to let the runtime hash uploaded bytes; include it to upload by content address, with the digest verified as the bytes land."),
     contentType: z.string().optional().describe("Optional content type for serving metadata."),
     sourceUrl: manifestSourceUrlSchema
         .optional()
         .describe("Optional HTTPS URL the runtime can fetch directly for this file instead of receiving bytes from the client."),
 });
-export const uploadManifestFileSchema = z
-    .union([
-    manifestFileSchema.extend({ sha256: manifestSha256Schema }),
-    manifestFileSchema.extend({ sourceUrl: manifestSourceUrlSchema }),
-])
-    .describe("A declared upload file. Local bytes require sha256. A sourceUrl entry may omit sha256 because the runtime computes it while fetching.");
+export const uploadManifestFileSchema = manifestFileSchema.describe("A declared upload file. sha256 is optional: omit it for runtime-hashed path uploads or sourceUrl fetches; include it for content-addressed uploads.");
 export const pendingUploadSchema = manifestFileSchema.pick({
     path: true,
     size: true,
@@ -87,9 +77,18 @@ export const uploadInstructionsSchema = z.object({
     targets: z
         .array(uploadTargetSchema)
         .default([])
-        .describe("Opaque upload targets, bounded by the instruction payload budget. Upload these, then call `links.resume` for the remainder."),
+        .describe("Opaque upload targets, bounded by the instruction payload budget. Upload these, then call `links.refresh` for the remainder."),
     links: z.object({
-        resume: z.string(),
+        // The key names the action — mint a fresh instruction page for whatever the
+        // session still needs — not the route that happens to serve it.
+        refresh: z.string(),
+        // Transition alias for clients baked before the rename (#2449). Deployed
+        // CLIs and dashboard bundles still *require* `links.resume`, so the server
+        // emits both keys with the same value and they keep parsing. Optional here
+        // so nothing new is forced to produce it. Remove — with the `/uploads/resume`
+        // route alias and the receipt's `links.resume` — once every baked client is
+        // rebuilt.
+        resume: z.string().optional(),
         finalize: z.string(),
     }),
     details: z

package/dist/contracts/mcp.d.ts

@@ -1,4 +1,21 @@
 import { z } from "zod";
+export declare const HOSTED_MCP_SERVER_VERSION: "2026-08-22";
+export declare const HOSTED_MCP_TOOL_CATALOG: readonly [{
+    readonly name: "execute";
+    readonly description: "Run JavaScript against the OpenAPI-generated Spacefast catalog in a secure sandbox.";
+}, {
+    readonly name: "skills";
+    readonly description: "Fetch Spacefast how-to guidance for an MCP workflow.";
+}, {
+    readonly name: "resume";
+    readonly description: "Resume an execution that paused for approval or input.";
+}, {
+    readonly name: "publish";
+    readonly description: "Publish inline files as a new immutable Spacefast version.";
+}, {
+    readonly name: "search_docs";
+    readonly description: "Search the published Spacefast documentation. An exact slug or path returns that page in full.";
+}];
 export declare const hostedMcpSessionStatusSchema: z.ZodEnum<{
     active: "active";
     expired: "expired";
@@ -155,6 +172,16 @@ export declare const hostedMcpDashboardResponseSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+export declare const hostedMcpProxyTokenSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    expiresAt: z.ZodString;
+}, z.core.$strip>;
+export declare const hostedMcpProxyTokenResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        accessToken: z.ZodString;
+        expiresAt: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 export declare const hostedMcpCloseSessionResponseSchema: z.ZodObject<{
     data: z.ZodObject<{
         sessionId: z.ZodString;
@@ -243,5 +270,6 @@ export declare const hostedMcpApprovalResponseSchema: z.ZodObject<{
 export type HostedMcpSession = z.infer<typeof hostedMcpSessionSchema>;
 export type HostedMcpSessionEvent = z.infer<typeof hostedMcpSessionEventSchema>;
 export type HostedMcpDashboard = z.infer<typeof hostedMcpDashboardSchema>;
+export type HostedMcpProxyToken = z.infer<typeof hostedMcpProxyTokenSchema>;
 export type HostedMcpPausedExecution = z.infer<typeof hostedMcpPausedExecutionSchema>;
 export type HostedMcpApprovalAction = z.infer<typeof hostedMcpApprovalActionSchema>;

package/dist/contracts/mcp.js

@@ -1,5 +1,28 @@
 import { z } from "zod";
 import { AnyObjectSchema, dataEnvelope } from "./common.js";
+export const HOSTED_MCP_SERVER_VERSION = "2026-08-22";
+export const HOSTED_MCP_TOOL_CATALOG = [
+    {
+        name: "execute",
+        description: "Run JavaScript against the OpenAPI-generated Spacefast catalog in a secure sandbox.",
+    },
+    {
+        name: "skills",
+        description: "Fetch Spacefast how-to guidance for an MCP workflow.",
+    },
+    {
+        name: "resume",
+        description: "Resume an execution that paused for approval or input.",
+    },
+    {
+        name: "publish",
+        description: "Publish inline files as a new immutable Spacefast version.",
+    },
+    {
+        name: "search_docs",
+        description: "Search the published Spacefast documentation. An exact slug or path returns that page in full.",
+    },
+];
 export const hostedMcpSessionStatusSchema = z.enum(["active", "closed", "expired", "interrupted"]);
 export const hostedMcpSessionSchema = z.object({
     sessionId: z.string(),
@@ -50,6 +73,11 @@ export const hostedMcpDashboardSchema = z.object({
     events: z.array(hostedMcpSessionEventSchema),
 });
 export const hostedMcpDashboardResponseSchema = dataEnvelope(hostedMcpDashboardSchema);
+export const hostedMcpProxyTokenSchema = z.object({
+    accessToken: z.string().min(1),
+    expiresAt: z.string().datetime(),
+});
+export const hostedMcpProxyTokenResponseSchema = dataEnvelope(hostedMcpProxyTokenSchema);
 export const hostedMcpCloseSessionResponseSchema = dataEnvelope(hostedMcpSessionSchema);
 export const hostedMcpSessionEventsResponseSchema = dataEnvelope(z.object({
     session: hostedMcpSessionSchema,

package/dist/contracts/me.d.ts

@@ -16,6 +16,12 @@ export declare const meResponseSchema: z.ZodObject<{
         isAutomattician: z.ZodBoolean;
         wpcom: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         isSuperadmin: z.ZodBoolean;
+        pendingDeletionAt: z.ZodNullable<z.ZodString>;
+        dashboardPrefs: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        privacy: z.ZodObject<{
+            analyticsOptOut: z.ZodBoolean;
+            advertisingOptOut: z.ZodBoolean;
+        }, z.core.$strip>;
     }, z.core.$strip>>;
     tenants: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -65,7 +71,6 @@ export declare const meResponseSchema: z.ZodObject<{
     beta: z.ZodObject<{
         gateEnabled: z.ZodBoolean;
         enrolled: z.ZodBoolean;
-        wpcom: z.ZodBoolean;
         eligibleTeams: z.ZodArray<z.ZodObject<{
             teamId: z.ZodString;
             name: z.ZodString;

package/dist/contracts/me.js

@@ -1,11 +1,12 @@
 import { z } from "zod";
 import { betaEligibleTeamSourceSchema } from "./beta.js";
+import { dashboardPrefsSchema } from "./dashboard-prefs.js";
 import { planCodeSchema } from "./features.js";
-// `GET /v1/me` (internal-docs/platform.md route catalog): the authenticated
-// subject, its tenant grants, principal/team memberships, and a plan summary.
-// Works for every credential kind — sessions resolve their user and team
-// memberships; machine credentials resolve the teams and tenants their policy
-// grants.
+import { privacySettingsSchema } from "./privacy.js";
+// `GET /v1/me` (the platform spec route catalog): the authenticated subject, its
+// tenant grants, principal/team memberships, and a plan summary. Sessions
+// resolve their user and team memberships; machine credentials resolve the teams
+// and tenants their policy grants.
 export const meResponseSchema = z.object({
     subject: z
         .object({
@@ -28,6 +29,12 @@ export const meResponseSchema = z.object({
             .nullable()
             .describe("Raw WordPress.com `/me` payload from the user's last WP.com login."),
         isSuperadmin: z.boolean().describe("Whether the user is a platform operator."),
+        pendingDeletionAt: z
+            .string()
+            .nullable()
+            .describe("When this account's deletion was requested, while the close is still running. Null for every account that is not being deleted."),
+        dashboardPrefs: dashboardPrefsSchema.describe("The user's dashboard preferences. Carried on the boot payload the dashboard already fetches, so applying a cross-device preference costs no extra request. Write with `PATCH /v1/me/dashboard-preferences`."),
+        privacy: privacySettingsSchema.describe("The user's account-level privacy choices. Write with `PATCH /v1/me/privacy`."),
     })
         .nullable()
         .describe("Authenticated user identity for user-subject credentials. Null for team-subject or service-subject machine credentials. Creator metadata is retained only for audit attribution, not request identity."),
@@ -89,7 +96,6 @@ export const meResponseSchema = z.object({
         enrolled: z
             .boolean()
             .describe("Whether the subject user is enrolled (beta_enrolled_at is set)."),
-        wpcom: z.boolean().describe("Whether the user passed the Automattician check at enrollment."),
         eligibleTeams: z
             .array(z.object({
             teamId: z.string().describe("Team id."),

package/dist/contracts/notifications.d.ts

@@ -38,36 +38,34 @@ export declare const notificationListQuerySchema: z.ZodObject<{
     unread: z.ZodDefault<z.ZodOptional<z.ZodCodec<z.ZodString, z.ZodBoolean>>>;
 }, z.core.$strip>;
 export declare const notificationListResponseSchema: z.ZodObject<{
-    data: z.ZodObject<{
-        notifications: z.ZodArray<z.ZodObject<{
-            id: z.ZodString;
-            kind: z.ZodEnum<{
-                "comment.created": "comment.created";
-                "comment.replied": "comment.replied";
-                "thread.archived": "thread.archived";
-                "thread.unarchived": "thread.unarchived";
-                mention: "mention";
-            }>;
-            teamId: z.ZodNullable<z.ZodString>;
-            spaceId: z.ZodNullable<z.ZodString>;
-            threadId: z.ZodNullable<z.ZodString>;
-            title: z.ZodString;
-            body: z.ZodNullable<z.ZodString>;
-            actor: z.ZodObject<{
-                name: z.ZodNullable<z.ZodString>;
-                avatarUrl: z.ZodNullable<z.ZodString>;
-                color: z.ZodNullable<z.ZodString>;
-            }, z.core.$strip>;
-            path: z.ZodNullable<z.ZodString>;
-            versionId: z.ZodNullable<z.ZodString>;
-            link: z.ZodNullable<z.ZodString>;
-            readAt: z.ZodNullable<z.ZodString>;
-            createdAt: z.ZodString;
-        }, z.core.$strip>>;
-        pagination: z.ZodObject<{
-            nextCursor: z.ZodNullable<z.ZodString>;
-            hasMore: z.ZodBoolean;
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            "comment.created": "comment.created";
+            "comment.replied": "comment.replied";
+            "thread.archived": "thread.archived";
+            "thread.unarchived": "thread.unarchived";
+            mention: "mention";
+        }>;
+        teamId: z.ZodNullable<z.ZodString>;
+        spaceId: z.ZodNullable<z.ZodString>;
+        threadId: z.ZodNullable<z.ZodString>;
+        title: z.ZodString;
+        body: z.ZodNullable<z.ZodString>;
+        actor: z.ZodObject<{
+            name: z.ZodNullable<z.ZodString>;
+            avatarUrl: z.ZodNullable<z.ZodString>;
+            color: z.ZodNullable<z.ZodString>;
         }, z.core.$strip>;
+        path: z.ZodNullable<z.ZodString>;
+        versionId: z.ZodNullable<z.ZodString>;
+        link: z.ZodNullable<z.ZodString>;
+        readAt: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const notificationUnreadCountResponseSchema: z.ZodObject<{

package/dist/contracts/notifications.js

@@ -28,12 +28,17 @@ export const notificationSchema = z.object({
     createdAt: z.string().datetime(),
 });
 export const notificationListQuerySchema = cursorListQuerySchema.extend({
-    unread: z.stringbool().optional().default(false),
+    unread: z
+        .stringbool()
+        .optional()
+        .default(false)
+        .describe("Return only notifications that have not been read yet."),
 });
-export const notificationListResponseSchema = dataEnvelope(z.object({
-    notifications: z.array(notificationSchema),
+// The one platform list envelope: items in `data[]`, page state beside it.
+export const notificationListResponseSchema = z.object({
+    data: z.array(notificationSchema),
     pagination: CursorPaginationSchema,
-}));
+});
 export const notificationUnreadCountResponseSchema = dataEnvelope(z.object({ count: z.number().int().nonnegative() }));
 export const notificationReadRequestSchema = z.object({
     ids: z.array(z.string().min(1)).max(100).optional(),

package/dist/contracts/oauth-resources.d.ts

@@ -3,19 +3,19 @@ export declare const OAUTH_AUTHORIZATION_SERVER_PATH: "/v1/auth";
  * mcp origin (`https://mcp.<domain>`), so it has no path entry here. */
 export declare const OAUTH_API_RESOURCE_PATH: "/v1";
 export type OAuthResourceKey = "api" | "mcp";
+export declare const OAUTH_SHARED_API_RESOURCE_SCOPES: readonly ["teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write"];
 export declare const OAUTH_API_RESOURCE_SCOPES: readonly ["teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "spaces:publish", "builds:trigger"];
-export declare const OAUTH_MCP_TOOL_SCOPE: "mcp:tools";
 export declare const OAUTH_OFFLINE_ACCESS_SCOPE: "offline_access";
-export declare const OAUTH_MCP_RESOURCE_SCOPES: readonly ["mcp:tools", "teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write"];
+export declare const OAUTH_MCP_RESOURCE_SCOPES: readonly ["teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write"];
 /**
  * A resource's `allowedScopes` is intersected with the requested scopes on every
- * token request, and the refresh token stores that intersection — so a resource
+ * token request, and the refresh token stores that intersection, so a resource
  * that omits `offline_access` cannot mint a refresh token that survives
  * rotation, and its clients must re-consent in a browser every
  * `accessTokenTtlSeconds`. Kept separate from OAUTH_MCP_RESOURCE_SCOPES, which
- * is the list of capabilities the dashboard and CLI offer per agent account.
+ * is the list of capabilities the dashboard and CLI offer per machine OAuth client.
  */
-export declare const OAUTH_MCP_RESOURCE_ALLOWED_SCOPES: readonly ["mcp:tools", "teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "offline_access"];
+export declare const OAUTH_MCP_RESOURCE_ALLOWED_SCOPES: readonly ["teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "offline_access"];
 export declare const OAUTH_API_RESOURCE_ALLOWED_SCOPES: readonly ["teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "spaces:publish", "builds:trigger", "offline_access"];
 /**
  * Interactive MCP clients should be useful after one consent. Authorization is
@@ -23,8 +23,110 @@ export declare const OAUTH_API_RESOURCE_ALLOWED_SCOPES: readonly ["teams:read",
  * sensitive execution; these scopes only let the MCP resource represent those
  * capabilities. Machine clients may continue to request a narrower set.
  */
-export declare const OAUTH_MCP_DEFAULT_SCOPES: readonly ["mcp:tools", "teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "offline_access"];
-export declare const OAUTH_PROVIDER_SCOPES: readonly ["openid", "profile", "email", "offline_access", "teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "spaces:publish", "builds:trigger", "mcp:tools"];
+export declare const OAUTH_MCP_DEFAULT_SCOPES: readonly ["teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "offline_access"];
+export declare const OAUTH_PROVIDER_SCOPES: readonly ["openid", "profile", "email", "offline_access", "teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "spaces:publish", "builds:trigger"];
+export declare const OAUTH_SCOPE_DESCRIPTIONS: {
+    readonly openid: "Identify the signed-in account.";
+    readonly profile: "Read the signed-in account's basic profile.";
+    readonly email: "Read the signed-in account's email address.";
+    readonly offline_access: "Refresh access without another interactive sign-in.";
+    readonly "teams:read": "Read the teams the account belongs to.";
+    readonly "teams:create": "Create teams.";
+    readonly "spaces:read": "Read spaces, versions, and build status.";
+    readonly "spaces:write": "Create and update spaces and their settings.";
+    readonly "spaces:rename": "Rename space slugs and managed addresses.";
+    readonly "publish:write": "Publish new immutable versions.";
+    readonly "spaces:publish": "Publish a version to an existing space.";
+    readonly "builds:trigger": "Start a build for an existing version.";
+    readonly "domains:read": "Read domain inventory and DNS diagnostics.";
+    readonly "domains:write": "Attach, verify, and mutate domains and DNS records.";
+};
+export declare const OAUTH_SCOPE_RISK_TINTS: readonly ["neutral", "warning", "critical"];
+export type OAuthScopeRiskTint = (typeof OAUTH_SCOPE_RISK_TINTS)[number];
+export type OAuthScopeId = keyof typeof OAUTH_SCOPE_DESCRIPTIONS;
+export type OAuthScopeCopy = {
+    label: string;
+    description: string;
+    riskTint: OAuthScopeRiskTint;
+};
+/**
+ * Human-facing permission copy shared by every authorization surface. Keep raw
+ * OAuth scope ids in developer views only; consent, approvals, ledgers, CLI
+ * prompts, and email should all render this vocabulary.
+ */
+export declare const OAUTH_SCOPE_COPY: {
+    readonly openid: {
+        readonly label: "Identify your account";
+        readonly description: "Identify the signed-in account.";
+        readonly riskTint: "neutral";
+    };
+    readonly profile: {
+        readonly label: "Read your profile";
+        readonly description: "Read the signed-in account's basic profile.";
+        readonly riskTint: "neutral";
+    };
+    readonly email: {
+        readonly label: "Read your email address";
+        readonly description: "Read the signed-in account's email address.";
+        readonly riskTint: "neutral";
+    };
+    readonly offline_access: {
+        readonly label: "Stay connected";
+        readonly description: "Refresh access without another interactive sign-in.";
+        readonly riskTint: "warning";
+    };
+    readonly "teams:read": {
+        readonly label: "Read your teams";
+        readonly description: "Read the teams the account belongs to.";
+        readonly riskTint: "neutral";
+    };
+    readonly "teams:create": {
+        readonly label: "Create teams";
+        readonly description: "Create teams.";
+        readonly riskTint: "warning";
+    };
+    readonly "spaces:read": {
+        readonly label: "Read your sites";
+        readonly description: "Read spaces, versions, and build status.";
+        readonly riskTint: "neutral";
+    };
+    readonly "spaces:write": {
+        readonly label: "Create and update your sites";
+        readonly description: "Create and update spaces and their settings.";
+        readonly riskTint: "warning";
+    };
+    readonly "spaces:rename": {
+        readonly label: "Rename your sites";
+        readonly description: "Rename space slugs and managed addresses.";
+        readonly riskTint: "warning";
+    };
+    readonly "publish:write": {
+        readonly label: "Publish and manage versions";
+        readonly description: "Publish new immutable versions.";
+        readonly riskTint: "warning";
+    };
+    readonly "spaces:publish": {
+        readonly label: "Publish new versions of your sites";
+        readonly description: "Publish a version to an existing space.";
+        readonly riskTint: "warning";
+    };
+    readonly "builds:trigger": {
+        readonly label: "Start builds";
+        readonly description: "Start a build for an existing version.";
+        readonly riskTint: "warning";
+    };
+    readonly "domains:read": {
+        readonly label: "Read your domains";
+        readonly description: "Read domain inventory and DNS diagnostics.";
+        readonly riskTint: "neutral";
+    };
+    readonly "domains:write": {
+        readonly label: "Manage domains and DNS";
+        readonly description: "Attach, verify, and mutate domains and DNS records.";
+        readonly riskTint: "critical";
+    };
+};
+export declare function oauthScopeCopy(scope: string): OAuthScopeCopy;
 export declare const OAUTH_RESOURCE_DEFINITIONS: {
     readonly api: {
         readonly key: "api";
@@ -36,14 +138,14 @@ export declare const OAUTH_RESOURCE_DEFINITIONS: {
         readonly key: "mcp";
         readonly name: "Spacefast MCP";
         readonly accessTokenTtlSeconds: number;
-        readonly allowedScopes: readonly ["mcp:tools", "teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "offline_access"];
+        readonly allowedScopes: readonly ["teams:read", "teams:create", "spaces:read", "spaces:write", "spaces:rename", "publish:write", "domains:read", "domains:write", "offline_access"];
     };
 };
 /** Resource identifier for the public API: `https://api.<domain>/v1`. */
 export declare function oauthApiResourceUrl(apiOrigin: string | URL): string;
 /**
  * Resource identifier for hosted MCP: the mcp origin itself, in RFC 8707
- * canonical form (lowercase scheme/host, no trailing slash) — this is the
+ * canonical form (lowercase scheme/host, no trailing slash). This is the
  * exact string MCP clients send as the `resource` parameter.
  */
 export declare function oauthMcpResourceUrl(mcpOrigin: string | URL): string;
@@ -51,7 +153,7 @@ export declare function normalizeOAuthResourceIdentifier(resource: string): stri
 /**
  * Derive the mcp origin from a configured api origin (`api.X` → `mcp.X`).
  * Returns null when the api host doesn't follow the `api.` convention
- * (loopback dev, docker test hosts) — callers fall back to the api origin.
+ * (loopback dev, docker test hosts). Callers fall back to the api origin.
  */
 export declare function oauthMcpOriginFromApiOrigin(apiOrigin: string | URL): string | null;
 /**

package/dist/contracts/oauth-resources.js

@@ -2,7 +2,12 @@ export const OAUTH_AUTHORIZATION_SERVER_PATH = "/v1/auth";
 /** The API resource is a path on the api origin; the MCP resource is the whole
  * mcp origin (`https://mcp.<domain>`), so it has no path entry here. */
 export const OAUTH_API_RESOURCE_PATH = "/v1";
-const OAUTH_SHARED_API_RESOURCE_SCOPES = [
+// The scopes shared by the API resource, the MCP resource, and the interactive
+// approval surface. `spaces:publish` and `builds:trigger` are deliberately NOT
+// here: their actions are already covered by `publish:write`, so they exist
+// only as granular API-resource scopes for clients (e.g. the WordPress plugin)
+// that want to name them. Interactive approval and MCP speak this shared set.
+export const OAUTH_SHARED_API_RESOURCE_SCOPES = [
     "teams:read",
     "teams:create",
     "spaces:read",
@@ -17,19 +22,18 @@ export const OAUTH_API_RESOURCE_SCOPES = [
     "spaces:publish",
     "builds:trigger",
 ];
-export const OAUTH_MCP_TOOL_SCOPE = "mcp:tools";
 export const OAUTH_OFFLINE_ACCESS_SCOPE = "offline_access";
-export const OAUTH_MCP_RESOURCE_SCOPES = [
-    OAUTH_MCP_TOOL_SCOPE,
-    ...OAUTH_SHARED_API_RESOURCE_SCOPES,
-];
+// Hosted MCP is pure transport over the API: a session represents exactly the
+// shared API scopes, and each tool call is gated only by the underlying API
+// scope it exercises. So the MCP resource's scopes are the shared API set.
+export const OAUTH_MCP_RESOURCE_SCOPES = [...OAUTH_SHARED_API_RESOURCE_SCOPES];
 /**
  * A resource's `allowedScopes` is intersected with the requested scopes on every
- * token request, and the refresh token stores that intersection — so a resource
+ * token request, and the refresh token stores that intersection, so a resource
  * that omits `offline_access` cannot mint a refresh token that survives
  * rotation, and its clients must re-consent in a browser every
  * `accessTokenTtlSeconds`. Kept separate from OAUTH_MCP_RESOURCE_SCOPES, which
- * is the list of capabilities the dashboard and CLI offer per agent account.
+ * is the list of capabilities the dashboard and CLI offer per machine OAuth client.
  */
 export const OAUTH_MCP_RESOURCE_ALLOWED_SCOPES = [
     ...OAUTH_MCP_RESOURCE_SCOPES,
@@ -52,8 +56,109 @@ export const OAUTH_PROVIDER_SCOPES = [
     "email",
     OAUTH_OFFLINE_ACCESS_SCOPE,
     ...OAUTH_API_RESOURCE_SCOPES,
-    OAUTH_MCP_TOOL_SCOPE,
 ];
+export const OAUTH_SCOPE_DESCRIPTIONS = {
+    openid: "Identify the signed-in account.",
+    profile: "Read the signed-in account's basic profile.",
+    email: "Read the signed-in account's email address.",
+    offline_access: "Refresh access without another interactive sign-in.",
+    "teams:read": "Read the teams the account belongs to.",
+    "teams:create": "Create teams.",
+    "spaces:read": "Read spaces, versions, and build status.",
+    "spaces:write": "Create and update spaces and their settings.",
+    "spaces:rename": "Rename space slugs and managed addresses.",
+    "publish:write": "Publish new immutable versions.",
+    "spaces:publish": "Publish a version to an existing space.",
+    "builds:trigger": "Start a build for an existing version.",
+    "domains:read": "Read domain inventory and DNS diagnostics.",
+    "domains:write": "Attach, verify, and mutate domains and DNS records.",
+};
+export const OAUTH_SCOPE_RISK_TINTS = ["neutral", "warning", "critical"];
+/**
+ * Human-facing permission copy shared by every authorization surface. Keep raw
+ * OAuth scope ids in developer views only; consent, approvals, ledgers, CLI
+ * prompts, and email should all render this vocabulary.
+ */
+export const OAUTH_SCOPE_COPY = {
+    openid: {
+        label: "Identify your account",
+        description: OAUTH_SCOPE_DESCRIPTIONS.openid,
+        riskTint: "neutral",
+    },
+    profile: {
+        label: "Read your profile",
+        description: OAUTH_SCOPE_DESCRIPTIONS.profile,
+        riskTint: "neutral",
+    },
+    email: {
+        label: "Read your email address",
+        description: OAUTH_SCOPE_DESCRIPTIONS.email,
+        riskTint: "neutral",
+    },
+    offline_access: {
+        label: "Stay connected",
+        description: OAUTH_SCOPE_DESCRIPTIONS.offline_access,
+        riskTint: "warning",
+    },
+    "teams:read": {
+        label: "Read your teams",
+        description: OAUTH_SCOPE_DESCRIPTIONS["teams:read"],
+        riskTint: "neutral",
+    },
+    "teams:create": {
+        label: "Create teams",
+        description: OAUTH_SCOPE_DESCRIPTIONS["teams:create"],
+        riskTint: "warning",
+    },
+    "spaces:read": {
+        label: "Read your sites",
+        description: OAUTH_SCOPE_DESCRIPTIONS["spaces:read"],
+        riskTint: "neutral",
+    },
+    "spaces:write": {
+        label: "Create and update your sites",
+        description: OAUTH_SCOPE_DESCRIPTIONS["spaces:write"],
+        riskTint: "warning",
+    },
+    "spaces:rename": {
+        label: "Rename your sites",
+        description: OAUTH_SCOPE_DESCRIPTIONS["spaces:rename"],
+        riskTint: "warning",
+    },
+    "publish:write": {
+        label: "Publish and manage versions",
+        description: OAUTH_SCOPE_DESCRIPTIONS["publish:write"],
+        riskTint: "warning",
+    },
+    "spaces:publish": {
+        label: "Publish new versions of your sites",
+        description: OAUTH_SCOPE_DESCRIPTIONS["spaces:publish"],
+        riskTint: "warning",
+    },
+    "builds:trigger": {
+        label: "Start builds",
+        description: OAUTH_SCOPE_DESCRIPTIONS["builds:trigger"],
+        riskTint: "warning",
+    },
+    "domains:read": {
+        label: "Read your domains",
+        description: OAUTH_SCOPE_DESCRIPTIONS["domains:read"],
+        riskTint: "neutral",
+    },
+    "domains:write": {
+        label: "Manage domains and DNS",
+        description: OAUTH_SCOPE_DESCRIPTIONS["domains:write"],
+        riskTint: "critical",
+    },
+};
+export function oauthScopeCopy(scope) {
+    const match = Object.entries(OAUTH_SCOPE_COPY).find(([knownScope]) => knownScope === scope);
+    return (match?.[1] ?? {
+        label: "Additional Spacefast access",
+        description: "Review this permission in Spacefast before you approve it.",
+        riskTint: "critical",
+    });
+}
 export const OAUTH_RESOURCE_DEFINITIONS = {
     api: {
         key: "api",
@@ -74,7 +179,7 @@ export function oauthApiResourceUrl(apiOrigin) {
 }
 /**
  * Resource identifier for hosted MCP: the mcp origin itself, in RFC 8707
- * canonical form (lowercase scheme/host, no trailing slash) — this is the
+ * canonical form (lowercase scheme/host, no trailing slash). This is the
  * exact string MCP clients send as the `resource` parameter.
  */
 export function oauthMcpResourceUrl(mcpOrigin) {
@@ -98,7 +203,7 @@ export function normalizeOAuthResourceIdentifier(resource) {
 /**
  * Derive the mcp origin from a configured api origin (`api.X` → `mcp.X`).
  * Returns null when the api host doesn't follow the `api.` convention
- * (loopback dev, docker test hosts) — callers fall back to the api origin.
+ * (loopback dev, docker test hosts). Callers fall back to the api origin.
  */
 export function oauthMcpOriginFromApiOrigin(apiOrigin) {
     const url = new URL(apiOrigin);