@spacefast/common 0.0.26 → 0.2.1

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);

package/dist/contracts/oauth-scope-actions.d.ts

@@ -0,0 +1,90 @@
+import { type StatticAction } from "./api-keys.js";
+/**
+ * Tenant-admission actions — the ONE declaration the credential compiler and
+ * scope-grantability both read, so they cannot drift. These are account-level:
+ * compiled onto the tenant root and checked ONLY there (creating a
+ * not-yet-existing team has no team to hang on), so their reach across the
+ * shared tenant grants no team authority. Every other action is team-role:
+ * compiled per team and intersected with the holder's LIVE role there.
+ */
+export declare const TENANT_ADMISSION_ACTIONS: readonly ["teams:create"];
+export declare function isTenantAdmissionAction(action: StatticAction): boolean;
+/**
+ * The one table binding OAuth scopes to IAM-lite actions, in both directions.
+ *
+ * Each scope declares only the actions it adds, plus the narrower scopes it
+ * subsumes. Everything else is derived:
+ *
+ * - forward (`oauthScopeActions`): a scope grants its own actions plus every
+ *   action of the scopes it covers, transitively. That is also what an API-key
+ *   preset with the same name is allowed to do, so `credential-policy.ts`
+ *   compiles presets from here rather than from a second list.
+ * - inverse (`oauthScopesForActions`): a policy's actions name the scopes whose
+ *   *own* actions they reach. Covered actions are deliberately not signals —
+ *   otherwise a read-only policy would label itself `publish:write` just for
+ *   holding `spaces:read`.
+ *
+ * Keep both halves honest by editing one entry: adding an action to a scope
+ * widens the grant and the label together, and `oauth-resources.test.ts` pins
+ * the derivation's invariants.
+ */
+declare const OAUTH_SCOPE_GRAPH: {
+    readonly "teams:read": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["teams:read"];
+    };
+    readonly "teams:create": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["teams:create"];
+    };
+    readonly "spaces:read": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["spaces:read", "versions:read", "builds:read"];
+    };
+    readonly "spaces:write": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["spaces:create", "spaces:write"];
+    };
+    readonly "spaces:rename": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["spaces:rename"];
+    };
+    readonly "publish:write": {
+        readonly covers: readonly ["spaces:read", "spaces:write"];
+        readonly actions: readonly ["spaces:publish", "versions:promote", "versions:download", "builds:trigger", "builds:create"];
+    };
+    readonly "domains:read": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["domains:read"];
+    };
+    readonly "domains:write": {
+        readonly covers: readonly ["domains:read"];
+        readonly actions: readonly ["domains:create", "domains:verify", "domains:assign", "domains:bind", "domains:delete", "domains:dns.write", "domains:purchase"];
+    };
+    readonly "spaces:publish": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["spaces:publish"];
+    };
+    readonly "builds:trigger": {
+        readonly covers: readonly [];
+        readonly actions: readonly ["builds:trigger"];
+    };
+};
+export type OAuthScopeWithActions = keyof typeof OAUTH_SCOPE_GRAPH;
+export declare function oauthScopeHasActions(scope: string): scope is OAuthScopeWithActions;
+/**
+ * The scopes a credential policy can be *labelled* with: the capability set the
+ * dashboard and CLI offer per machine OAuth client. Derived from the graph's
+ * own order so the label list reads the way the consent screen does.
+ */
+export declare const OAUTH_PRIMARY_SCOPES: ("teams:read" | "teams:create" | "spaces:read" | "spaces:write" | "spaces:rename" | "publish:write" | "domains:read" | "domains:write" | "spaces:publish" | "builds:trigger")[];
+/** Every action a scope grants, including the scopes it subsumes. */
+export declare function oauthScopeActionsFor(scope: OAuthScopeWithActions): StatticAction[];
+/** Every action a set of scopes grants together. Unknown scopes grant nothing. */
+export declare function oauthScopeActions(scopes: readonly string[] | null | undefined): StatticAction[];
+/**
+ * The primary scopes a set of allowed actions amounts to. `*` is every primary
+ * scope; anything else matches on a scope's own actions only.
+ */
+export declare function oauthScopesForActions(actions: Iterable<string>): OAuthScopeWithActions[];
+export {};

package/dist/contracts/oauth-scope-actions.js

@@ -0,0 +1,126 @@
+import { StatticActionSchema } from "./api-keys.js";
+import { OAUTH_MCP_RESOURCE_SCOPES } from "./oauth-resources.js";
+/**
+ * Tenant-admission actions — the ONE declaration the credential compiler and
+ * scope-grantability both read, so they cannot drift. These are account-level:
+ * compiled onto the tenant root and checked ONLY there (creating a
+ * not-yet-existing team has no team to hang on), so their reach across the
+ * shared tenant grants no team authority. Every other action is team-role:
+ * compiled per team and intersected with the holder's LIVE role there.
+ */
+export const TENANT_ADMISSION_ACTIONS = [
+    "teams:create",
+];
+const TENANT_ADMISSION_ACTION_SET = new Set(TENANT_ADMISSION_ACTIONS);
+export function isTenantAdmissionAction(action) {
+    return TENANT_ADMISSION_ACTION_SET.has(action);
+}
+/**
+ * The one table binding OAuth scopes to IAM-lite actions, in both directions.
+ *
+ * Each scope declares only the actions it adds, plus the narrower scopes it
+ * subsumes. Everything else is derived:
+ *
+ * - forward (`oauthScopeActions`): a scope grants its own actions plus every
+ *   action of the scopes it covers, transitively. That is also what an API-key
+ *   preset with the same name is allowed to do, so `credential-policy.ts`
+ *   compiles presets from here rather than from a second list.
+ * - inverse (`oauthScopesForActions`): a policy's actions name the scopes whose
+ *   *own* actions they reach. Covered actions are deliberately not signals —
+ *   otherwise a read-only policy would label itself `publish:write` just for
+ *   holding `spaces:read`.
+ *
+ * Keep both halves honest by editing one entry: adding an action to a scope
+ * widens the grant and the label together, and `oauth-resources.test.ts` pins
+ * the derivation's invariants.
+ */
+const OAUTH_SCOPE_GRAPH = {
+    "teams:read": { covers: [], actions: ["teams:read"] },
+    "teams:create": { covers: [], actions: ["teams:create"] },
+    "spaces:read": {
+        covers: [],
+        actions: ["spaces:read", "versions:read", "builds:read"],
+    },
+    "spaces:write": { covers: [], actions: ["spaces:create", "spaces:write"] },
+    "spaces:rename": { covers: [], actions: ["spaces:rename"] },
+    // The publish tier is read + write plus the version and build verbs a
+    // publish flow needs. `spaces:publish` and `builds:trigger` are also offered
+    // on their own as granular API-resource scopes; they stay listed here as
+    // publish's own actions so a policy holding nothing but them still labels as
+    // a publisher.
+    "publish:write": {
+        covers: ["spaces:read", "spaces:write"],
+        actions: [
+            "spaces:publish",
+            "versions:promote",
+            "versions:download",
+            "builds:trigger",
+            "builds:create",
+        ],
+    },
+    "domains:read": { covers: [], actions: ["domains:read"] },
+    "domains:write": {
+        covers: ["domains:read"],
+        actions: [
+            "domains:create",
+            "domains:verify",
+            "domains:assign",
+            "domains:bind",
+            "domains:delete",
+            "domains:dns.write",
+            "domains:purchase",
+        ],
+    },
+    // Granular API-resource scopes. They never label a policy on their own — the
+    // inverse only ranges over the primary scopes below.
+    "spaces:publish": { covers: [], actions: ["spaces:publish"] },
+    "builds:trigger": { covers: [], actions: ["builds:trigger"] },
+};
+export function oauthScopeHasActions(scope) {
+    return scope in OAUTH_SCOPE_GRAPH;
+}
+const primaryScopeSet = new Set(OAUTH_MCP_RESOURCE_SCOPES);
+/**
+ * The scopes a credential policy can be *labelled* with: the capability set the
+ * dashboard and CLI offer per machine OAuth client. Derived from the graph's
+ * own order so the label list reads the way the consent screen does.
+ */
+export const OAUTH_PRIMARY_SCOPES = Object.keys(OAUTH_SCOPE_GRAPH)
+    .filter(oauthScopeHasActions)
+    .filter((scope) => primaryScopeSet.has(scope));
+// Derived action lists are emitted in `StatticActionSchema` order, so a
+// credential's permissions read the same however the graph is authored and a
+// reordered entry never churns the wire contract.
+const ACTION_ORDER = new Map(StatticActionSchema.options.map((action, index) => [action, index]));
+function actionsForScope(scope, seen) {
+    if (seen.has(scope))
+        return [];
+    seen.add(scope);
+    const entry = OAUTH_SCOPE_GRAPH[scope];
+    return [
+        ...entry.actions,
+        ...entry.covers
+            .filter(oauthScopeHasActions)
+            .flatMap((covered) => actionsForScope(covered, seen)),
+    ];
+}
+/** Every action a scope grants, including the scopes it subsumes. */
+export function oauthScopeActionsFor(scope) {
+    return [...new Set(actionsForScope(scope, new Set()))].toSorted((left, right) => (ACTION_ORDER.get(left) ?? 0) - (ACTION_ORDER.get(right) ?? 0));
+}
+/** Every action a set of scopes grants together. Unknown scopes grant nothing. */
+export function oauthScopeActions(scopes) {
+    return [
+        ...new Set((scopes ?? []).filter(oauthScopeHasActions).flatMap((scope) => oauthScopeActionsFor(scope))),
+    ];
+}
+/**
+ * The primary scopes a set of allowed actions amounts to. `*` is every primary
+ * scope; anything else matches on a scope's own actions only.
+ */
+export function oauthScopesForActions(actions) {
+    const allowed = new Set(actions);
+    if (allowed.has("*"))
+        return [...OAUTH_PRIMARY_SCOPES];
+    return OAUTH_PRIMARY_SCOPES.filter((scope) => OAUTH_SCOPE_GRAPH[scope].actions.some((action) => allowed.has(action)));
+}