@spacefast/common 0.0.5 → 0.0.6

package/dist/contracts/features.js

@@ -11,18 +11,31 @@ export const FEATURE_KEYS = [
     "domains.search",
     "domains.registration",
     "domains.dns_management",
+    "domains.wpcom_dns",
+    "domains.domain_connect",
     "domains.proxy_bindings",
     "annotations.preview_loader",
     "annotations.comments",
     "annotations.anonymous_reviewers",
     "annotations.cli",
     "annotations.notices",
-    "annotations.spacefast_token",
     "annotations.published_comments",
     "sites.dedicated_runtime",
     "shelf",
     "tags",
     "zero",
+    // Access product phases (access-plan §7, X-42): every phase ships behind its
+    // own dot-namespaced key, born internal-only. The lifecycle registry
+    // (stage/docsSlug per internal-docs/feature-lifecycle-plan.html) is not
+    // implemented yet — these use the existing FeatureDefinition shape with
+    // internal-only defaults until it lands.
+    "access.share_links",
+    "access.invites",
+    "access.firewall_card",
+    "access.sso_connections",
+    "access.byo_issuers",
+    "access.views_panel",
+    "pages.white_label",
 ];
 export const featureKeySchema = z.enum(FEATURE_KEYS).describe("Feature flag key.");
 // Feature override states (env `SPACEFAST_FLAG_*` and the feature_overrides
@@ -66,6 +79,27 @@ export const planLimitsSchema = z
     // Queryable analytics history window. Storage retains rollups for everyone
     // (env-bounded); this only clamps how far back the analytics API serves.
     analyticsRetentionDays: planLimitValueSchema,
+    // Access-surface abuse ceilings (access-plan §5.1, X-40): generous by
+    // default, enterprise unlimited — never upsell levers. Per-plan tightening
+    // (if ever) happens here, never as constants in route code.
+    // Cloud-lane rules per space (incl. TTL'd blocks; managed blocks excluded
+    // from the count).
+    cloudRulesPerSpace: planLimitValueSchema,
+    // Active (non-revoked, non-expired) share links per space.
+    shareLinksPerSpace: planLimitValueSchema,
+    // Active invites per space (§5.3 — enforced when invites land).
+    invitesPerSpace: planLimitValueSchema,
+    // Invite emails per space / per account, daily (§5.3 abuse posture).
+    inviteEmailsPerSpaceDaily: planLimitValueSchema,
+    inviteEmailsPerAccountDaily: planLimitValueSchema,
+    // Pending access requests per space (§5.4).
+    pendingAccessRequestsPerSpace: planLimitValueSchema,
+    // Service tokens per team (§5.5).
+    serviceTokensPerTeam: planLimitValueSchema,
+    // OIDC + external issuer connections per team (§6).
+    connectionsPerTeam: planLimitValueSchema,
+    // Team-default rules (X-24).
+    teamDefaultRules: planLimitValueSchema,
 })
     .describe("Named plan limit table.");
 // Resolved team entitlements: plan limits after add-on grants plus the
@@ -79,6 +113,16 @@ export const teamEntitlementsSchema = z
         .boolean()
         .describe("Whether `_headers` Basic-Auth rules compile on this plan."),
     externalProxy: z.boolean().describe("Whether external proxy upstreams compile on this plan."),
+    dedicatedRuntime: z.boolean().describe("Whether the team can use dedicated runtime sites."),
+    pagesWhiteLabel: z
+        .boolean()
+        .describe("Whether the pages.white_label tier compiles (Spacefast branding removed from gate pages)."),
+    pagesCustomHtml: z
+        .boolean()
+        .describe("Whether custom gate-page HTML compiles (401.html/403.html slot overrides and .spacefast/templates/layout.html chrome, access-plan §8/§9 paid tier 1)."),
+    pagesAdvancedTheming: z
+        .boolean()
+        .describe("Whether the sf.theme.jsonc escape-hatch theme tier compiles (access-plan §8/§9 paid tier 1); theme.json and pages.theme basics stay free."),
     runtimePhpWorkers: z.number().int().describe("PHP workers per serving site."),
     analyticsHourlyGranularity: z
         .boolean()
@@ -120,6 +164,29 @@ const UNLIMITED_LIMITS = {
     buildAccessLogRetentionHours: "unlimited",
     buildsDeploysMonthly: "unlimited",
     analyticsRetentionDays: "unlimited",
+    cloudRulesPerSpace: "unlimited",
+    shareLinksPerSpace: "unlimited",
+    invitesPerSpace: "unlimited",
+    inviteEmailsPerSpaceDaily: "unlimited",
+    inviteEmailsPerAccountDaily: "unlimited",
+    pendingAccessRequestsPerSpace: "unlimited",
+    serviceTokensPerTeam: "unlimited",
+    connectionsPerTeam: "unlimited",
+    teamDefaultRules: "unlimited",
+};
+// The §5.1 access abuse-ceiling table (X-40): applied verbatim to every
+// self-serve plan; enterprise/internal stay unlimited. These sit far above
+// honest use — they are abuse ceilings, not upsell levers.
+const ACCESS_QUOTA_DEFAULTS = {
+    cloudRulesPerSpace: 200,
+    shareLinksPerSpace: 100,
+    invitesPerSpace: 500,
+    inviteEmailsPerSpaceDaily: 200,
+    inviteEmailsPerAccountDaily: 500,
+    pendingAccessRequestsPerSpace: 100,
+    serviceTokensPerTeam: 50,
+    connectionsPerTeam: 10,
+    teamDefaultRules: 50,
 };
 export const PLAN_DEFINITIONS = {
     free: {
@@ -130,7 +197,7 @@ export const PLAN_DEFINITIONS = {
             storageBytes: 5 * GB,
             teamMembers: 3,
             subTeams: 0,
-            externalDomainGroups: 1,
+            externalDomainGroups: 3,
             publicImmutableVersionWindowDays: 7,
             versionRetentionDays: 30, // included full-retention window (charter A3)
             versionGatedKeepDays: 183, // kept gated ~6 months from readyAt, then deleted
@@ -142,9 +209,14 @@ export const PLAN_DEFINITIONS = {
             buildAccessLogRetentionHours: 48,
             buildsDeploysMonthly: 100,
             analyticsRetentionDays: 30,
+            ...ACCESS_QUOTA_DEFAULTS,
         },
         headersBasicAuth: false,
         externalProxy: false,
+        dedicatedRuntime: false,
+        pagesWhiteLabel: false,
+        pagesCustomHtml: false,
+        pagesAdvancedTheming: false,
         runtimePhpWorkers: 2,
         analyticsHourlyGranularity: false,
     },
@@ -164,9 +236,14 @@ export const PLAN_DEFINITIONS = {
             buildAccessLogRetentionHours: MONTH_HOURS,
             buildsDeploysMonthly: 1000,
             analyticsRetentionDays: 365,
+            ...ACCESS_QUOTA_DEFAULTS,
         },
         headersBasicAuth: true,
         externalProxy: true,
+        dedicatedRuntime: false,
+        pagesWhiteLabel: false,
+        pagesCustomHtml: true,
+        pagesAdvancedTheming: true,
         runtimePhpWorkers: 4,
         analyticsHourlyGranularity: true,
     },
@@ -182,9 +259,14 @@ export const PLAN_DEFINITIONS = {
             // "unlimited" limits, so this must stay numeric.
             teamMembers: 15,
             subTeams: 0,
+            ...ACCESS_QUOTA_DEFAULTS,
         },
         headersBasicAuth: true,
         externalProxy: true,
+        dedicatedRuntime: false,
+        pagesWhiteLabel: true,
+        pagesCustomHtml: true,
+        pagesAdvancedTheming: true,
         runtimePhpWorkers: 4,
         analyticsHourlyGranularity: true,
     },
@@ -196,6 +278,10 @@ export const PLAN_DEFINITIONS = {
         limits: { ...UNLIMITED_LIMITS },
         headersBasicAuth: true,
         externalProxy: true,
+        dedicatedRuntime: true,
+        pagesWhiteLabel: true,
+        pagesCustomHtml: true,
+        pagesAdvancedTheming: true,
         runtimePhpWorkers: 4,
         analyticsHourlyGranularity: true,
     },
@@ -206,6 +292,10 @@ export const PLAN_DEFINITIONS = {
         limits: { ...UNLIMITED_LIMITS },
         headersBasicAuth: true,
         externalProxy: true,
+        dedicatedRuntime: true,
+        pagesWhiteLabel: true,
+        pagesCustomHtml: true,
+        pagesAdvancedTheming: true,
         runtimePhpWorkers: 4,
         analyticsHourlyGranularity: true,
     },
@@ -264,6 +354,22 @@ export const FEATURE_DEFINITIONS = {
         enabledForA8c: true,
         planDefaults: {},
     },
+    "domains.wpcom_dns": {
+        key: "domains.wpcom_dns",
+        name: "WordPress.com DNS automation",
+        description: "Manage a domain's DNS through the owner's WordPress.com account.",
+        defaultEnabled: false,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "domains.domain_connect": {
+        key: "domains.domain_connect",
+        name: "Domain Connect",
+        description: "One-click DNS setup at providers that implement Domain Connect.",
+        defaultEnabled: false,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
     "domains.proxy_bindings": {
         key: "domains.proxy_bindings",
         name: "Domain proxy bindings",
@@ -317,23 +423,14 @@ export const FEATURE_DEFINITIONS = {
         enabledForA8c: true,
         planDefaults: {},
     },
-    "annotations.spacefast_token": {
-        key: "annotations.spacefast_token",
-        name: "Spacefast-native annotation tokens",
-        description: "Mints collaboration tokens as Spacefast EdDSA access tokens (dedicated Cast kid) instead of the legacy HS256 path; the Spacefast-native auth cutover.",
-        defaultEnabled: false,
-        enabledInDevelopment: true,
-        enabledForA8c: true,
-        planDefaults: {},
-    },
     "annotations.published_comments": {
         key: "annotations.published_comments",
         name: "Published host annotation comments",
         description: "Allows the annotation overlay to mount comments on a space's live/published host, not just immutable preview URLs.",
         defaultEnabled: false,
         // ON in local dev so the Spacefast-native published path is exercised end-to-end
-        // alongside annotations.comments + annotations.spacefast_token (which already
-        // default on in dev). Production stays gated behind the per-space toggle.
+        // alongside annotations.comments (which already defaults on in dev).
+        // Production stays gated behind the per-space toggle.
         enabledInDevelopment: true,
         enabledForA8c: true,
         planDefaults: {},
@@ -373,6 +470,74 @@ export const FEATURE_DEFINITIONS = {
         enabledForA8c: true,
         planDefaults: {},
     },
+    // Access product phases (access-plan §7, X-42). Shipped surfaces default on;
+    // later-stage identity-provider pieces stay override-gated until they are
+    // ready for the main product path. When the lifecycle registry (stage +
+    // docsSlug, internal-docs/feature-lifecycle-plan.html) lands, these migrate
+    // onto it.
+    "access.share_links": {
+        key: "access.share_links",
+        name: "Share links",
+        description: "Enables the Share modal's sharing projection, the general-access selector, and share-link create/copy/revoke (access-plan §5.1/§5.2).",
+        defaultEnabled: true,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "access.invites": {
+        key: "access.invites",
+        name: "Space invites",
+        description: "Enables account-less viewer invites with magic-link accept and the request-access loop (access-plan §5.3/§5.4).",
+        defaultEnabled: false,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "access.firewall_card": {
+        key: "access.firewall_card",
+        name: "Firewall card",
+        description: "Enables the managed firewall block card (country/IP/bot rules) in space access settings (access-plan §5.6).",
+        defaultEnabled: true,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "access.sso_connections": {
+        key: "access.sso_connections",
+        name: "Company SSO connections",
+        description: "Enables team-level OIDC connections minted at the authorize endpoint (access-plan §6.2, X-18).",
+        defaultEnabled: false,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "access.byo_issuers": {
+        key: "access.byo_issuers",
+        name: "Bring-your-own issuers",
+        description: "Enables owner-held external token issuers with ext:-namespace binding (access-plan §6.3, X-19).",
+        defaultEnabled: false,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "access.views_panel": {
+        key: "access.views_panel",
+        name: "Views panel",
+        description: "Enables the identified who-viewed-what panel riding the analytics tiers (access-plan §5.6b, X-28).",
+        defaultEnabled: true,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "pages.white_label": {
+        key: "pages.white_label",
+        name: "White-label platform pages",
+        description: "Removes Spacefast branding from the challenge/deny page tier between theme tokens and full custom pages (access-plan §5.7, X-16).",
+        defaultEnabled: false,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
 };
 export const featureStateSourceSchema = z
     .enum(["kill_switch", "env", "override", "default"])

package/dist/contracts/git.d.ts

@@ -2,13 +2,13 @@ import { z } from "zod";
 export declare const buildTargetValues: readonly ["production", "preview"];
 export declare const buildTriggerValues: readonly ["manual", "push", "pull_request", "retry"];
 export declare const buildTarget: z.ZodEnum<{
-    preview: "preview";
     production: "production";
+    preview: "preview";
 }>;
 export declare const buildTrigger: z.ZodEnum<{
     push: "push";
-    pull_request: "pull_request";
     manual: "manual";
+    pull_request: "pull_request";
     retry: "retry";
 }>;
 export declare const buildEnvironmentScopeValues: readonly ["runtime", "build", "build:production", "build:preview"];
@@ -279,10 +279,4 @@ export declare const githubRepositorySchema: z.ZodObject<{
     private: z.ZodBoolean;
 }, z.core.$strip>;
 export type BuildTarget = z.infer<typeof buildTarget>;
-export type BuildTrigger = z.infer<typeof buildTrigger>;
-export type BuildEnvironmentScope = z.infer<typeof buildEnvironmentScope>;
 export type GitBuildSettings = z.infer<typeof gitBuildSettingsSchema>;
-export type GitConnection = z.infer<typeof gitConnectionSchema>;
-export type GitConnectionCreate = z.infer<typeof gitConnectionCreateSchema>;
-export type GitConnectionPatch = z.infer<typeof gitConnectionPatchSchema>;
-export type GitConnectionAnalyzeResponse = z.infer<typeof gitConnectionAnalyzeResponseSchema>;

package/dist/contracts/ids.d.ts

@@ -26,6 +26,11 @@ export declare const ID_PREFIXES: {
     readonly tga: "TagRuntimeArtifact";
     readonly tgp: "TagPreviewSession";
     readonly bhk: "BuildHook";
+    readonly lnk: "ShareLink";
+    readonly sin: "SpaceInvite";
+    readonly arq: "AccessRequest";
+    readonly stk: "ServiceToken";
+    readonly acn: "AccessConnection";
 };
 export type IdPrefix = keyof typeof ID_PREFIXES;
 /** Any registered public resource id, e.g. `spc_…` or `ver_…`. */

package/dist/contracts/ids.js

@@ -34,6 +34,11 @@ export const ID_PREFIXES = {
     tgp: "TagPreviewSession",
     // Reserved for the deferred build-hook surface; never minted yet.
     bhk: "BuildHook",
+    lnk: "ShareLink",
+    sin: "SpaceInvite",
+    arq: "AccessRequest",
+    stk: "ServiceToken",
+    acn: "AccessConnection",
 };
 // The main Stattic tenant every self-serve team/user/resource lives under. A
 // well-known CONSTANT, never configuration: grammatically a normal tenant id with

package/dist/contracts/mcp.d.ts

@@ -51,8 +51,8 @@ export declare const hostedMcpApprovalSchema: z.ZodObject<{
     status: z.ZodEnum<{
         expired: "expired";
         pending: "pending";
-        denied: "denied";
         approved: "approved";
+        denied: "denied";
         consumed: "consumed";
     }>;
     decision: z.ZodNullable<z.ZodEnum<{
@@ -167,8 +167,8 @@ export declare const hostedMcpExecutionRunSchema: z.ZodObject<{
 export declare const hostedMcpToolPolicySchema: z.ZodObject<{
     tool: z.ZodString;
     runtime: z.ZodEnum<{
-        hosted: "hosted";
         "on-device": "on-device";
+        hosted: "hosted";
         both: "both";
     }>;
     category: z.ZodString;
@@ -191,8 +191,8 @@ export declare const hostedMcpPolicyDefaultsSchema: z.ZodObject<{
     toolPolicies: z.ZodArray<z.ZodObject<{
         tool: z.ZodString;
         runtime: z.ZodEnum<{
-            hosted: "hosted";
             "on-device": "on-device";
+            hosted: "hosted";
             both: "both";
         }>;
         category: z.ZodString;
@@ -257,8 +257,8 @@ export declare const hostedMcpDashboardSchema: z.ZodObject<{
         toolPolicies: z.ZodArray<z.ZodObject<{
             tool: z.ZodString;
             runtime: z.ZodEnum<{
-                hosted: "hosted";
                 "on-device": "on-device";
+                hosted: "hosted";
                 both: "both";
             }>;
             category: z.ZodString;
@@ -314,8 +314,8 @@ export declare const hostedMcpDashboardSchema: z.ZodObject<{
         status: z.ZodEnum<{
             expired: "expired";
             pending: "pending";
-            denied: "denied";
             approved: "approved";
+            denied: "denied";
             consumed: "consumed";
         }>;
         decision: z.ZodNullable<z.ZodEnum<{
@@ -422,8 +422,8 @@ export declare const hostedMcpDashboardResponseSchema: z.ZodObject<{
             toolPolicies: z.ZodArray<z.ZodObject<{
                 tool: z.ZodString;
                 runtime: z.ZodEnum<{
-                    hosted: "hosted";
                     "on-device": "on-device";
+                    hosted: "hosted";
                     both: "both";
                 }>;
                 category: z.ZodString;
@@ -479,8 +479,8 @@ export declare const hostedMcpDashboardResponseSchema: z.ZodObject<{
             status: z.ZodEnum<{
                 expired: "expired";
                 pending: "pending";
-                denied: "denied";
                 approved: "approved";
+                denied: "denied";
                 consumed: "consumed";
             }>;
             decision: z.ZodNullable<z.ZodEnum<{
@@ -608,8 +608,8 @@ export declare const hostedMcpApprovalResponseSchema: z.ZodObject<{
         status: z.ZodEnum<{
             expired: "expired";
             pending: "pending";
-            denied: "denied";
             approved: "approved";
+            denied: "denied";
             consumed: "consumed";
         }>;
         decision: z.ZodNullable<z.ZodEnum<{
@@ -776,9 +776,7 @@ export declare const hostedMcpExecutionRunResponseSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type HostedMcpSession = z.infer<typeof hostedMcpSessionSchema>;
-export type HostedMcpWorkspaceSummary = z.infer<typeof hostedMcpWorkspaceSummarySchema>;
 export type HostedMcpApproval = z.infer<typeof hostedMcpApprovalSchema>;
-export type HostedMcpApprovalDecisionRequest = z.infer<typeof hostedMcpApprovalDecisionRequestSchema>;
 export type HostedMcpSessionEvent = z.infer<typeof hostedMcpSessionEventSchema>;
 export type HostedMcpExecutionRun = z.infer<typeof hostedMcpExecutionRunSchema>;
 export type HostedMcpExecutionStep = z.infer<typeof hostedMcpExecutionStepSchema>;

package/dist/contracts/me.js

@@ -97,7 +97,7 @@ export const meResponseSchema = z.object({
             slug: z.string().nullable().describe("Team slug."),
             source: betaEligibleTeamSourceSchema,
         }))
-            .describe("Teams the user may join via the picker (pending invitation or auto-enroll match)."),
+            .describe("Teams the user may join via the picker (pending invitation, auto-enroll match, or Automattician access)."),
     })
         .describe("Private-beta state. Dashboards key the blocked screen on gateEnabled && !enrolled, " +
         "never on !enrolled alone — else launch-day flag-off would still block people."),

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

@@ -1,9 +1,8 @@
 export declare const OAUTH_AUTHORIZATION_SERVER_PATH: "/v1/auth";
-export declare const OAUTH_RESOURCE_PATHS: {
-    readonly api: "/v1";
-    readonly mcp: "/mcp";
-};
-export type OAuthResourceKey = keyof typeof OAUTH_RESOURCE_PATHS;
+/** 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 declare const OAUTH_API_RESOURCE_PATH: "/v1";
+export type OAuthResourceKey = "api" | "mcp";
 export declare const OAUTH_API_RESOURCE_SCOPES: readonly ["teams:read", "spaces:read", "spaces:write", "publish:write", "domains:read", "domains:write"];
 export declare const OAUTH_MCP_TOOL_SCOPE: "mcp:tools";
 export declare const OAUTH_MCP_RESOURCE_SCOPES: readonly ["mcp:tools", "teams:read", "spaces:read", "spaces:write", "publish:write", "domains:read", "domains:write"];
@@ -11,20 +10,32 @@ export declare const OAUTH_PROVIDER_SCOPES: readonly ["openid", "profile", "emai
 export declare const OAUTH_RESOURCE_DEFINITIONS: {
     readonly api: {
         readonly key: "api";
-        readonly path: "/v1";
         readonly name: "Spacefast API";
         readonly accessTokenTtlSeconds: number;
         readonly allowedScopes: readonly ["teams:read", "spaces:read", "spaces:write", "publish:write", "domains:read", "domains:write"];
     };
     readonly mcp: {
         readonly key: "mcp";
-        readonly path: "/mcp";
         readonly name: "Spacefast MCP";
         readonly accessTokenTtlSeconds: number;
         readonly allowedScopes: readonly ["mcp:tools", "teams:read", "spaces:read", "spaces:write", "publish:write", "domains:read", "domains:write"];
     };
 };
-export declare function oauthResourceUrl(origin: string | URL, resource: OAuthResourceKey): string;
+/** 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
+ * exact string MCP clients send as the `resource` parameter.
+ */
+export declare function oauthMcpResourceUrl(mcpOrigin: string | URL): string;
+export declare function normalizeOAuthResourceIdentifier(resource: string): string;
+/**
+ * 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.
+ */
+export declare function oauthMcpOriginFromApiOrigin(apiOrigin: string | URL): string | null;
 export declare function oauthAuthorizationServerUrl(origin: string | URL): string;
 export declare function oauthTokenEndpointUrl(origin: string | URL): string;
 export declare function oauthResourceKeyForPathname(pathname: string): OAuthResourceKey | null;

package/dist/contracts/oauth-resources.js

@@ -1,8 +1,7 @@
 export const OAUTH_AUTHORIZATION_SERVER_PATH = "/v1/auth";
-export const OAUTH_RESOURCE_PATHS = {
-    api: "/v1",
-    mcp: "/mcp",
-};
+/** 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";
 export const OAUTH_API_RESOURCE_SCOPES = [
     "teams:read",
     "spaces:read",
@@ -27,21 +26,56 @@ export const OAUTH_PROVIDER_SCOPES = [
 export const OAUTH_RESOURCE_DEFINITIONS = {
     api: {
         key: "api",
-        path: OAUTH_RESOURCE_PATHS.api,
         name: "Spacefast API",
         accessTokenTtlSeconds: 15 * 60,
         allowedScopes: OAUTH_API_RESOURCE_SCOPES,
     },
     mcp: {
         key: "mcp",
-        path: OAUTH_RESOURCE_PATHS.mcp,
         name: "Spacefast MCP",
         accessTokenTtlSeconds: 15 * 60,
         allowedScopes: OAUTH_MCP_RESOURCE_SCOPES,
     },
 };
-export function oauthResourceUrl(origin, resource) {
-    return new URL(OAUTH_RESOURCE_PATHS[resource], origin).toString();
+/** Resource identifier for the public API: `https://api.<domain>/v1`. */
+export function oauthApiResourceUrl(apiOrigin) {
+    return new URL(OAUTH_API_RESOURCE_PATH, apiOrigin).toString();
+}
+/**
+ * Resource identifier for hosted MCP: the mcp origin itself, in RFC 8707
+ * canonical form (lowercase scheme/host, no trailing slash) — this is the
+ * exact string MCP clients send as the `resource` parameter.
+ */
+export function oauthMcpResourceUrl(mcpOrigin) {
+    return new URL(mcpOrigin).origin;
+}
+export function normalizeOAuthResourceIdentifier(resource) {
+    const trimmed = resource.trim();
+    if (!trimmed) {
+        return trimmed;
+    }
+    const url = new URL(trimmed);
+    if (!url.search && !url.hash && url.pathname === "/") {
+        return url.origin;
+    }
+    if (!url.search && !url.hash && url.pathname === `${OAUTH_API_RESOURCE_PATH}/`) {
+        url.pathname = OAUTH_API_RESOURCE_PATH;
+        return url.toString();
+    }
+    return url.toString();
+}
+/**
+ * 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.
+ */
+export function oauthMcpOriginFromApiOrigin(apiOrigin) {
+    const url = new URL(apiOrigin);
+    if (!url.hostname.startsWith("api.")) {
+        return null;
+    }
+    url.hostname = `mcp.${url.hostname.slice("api.".length)}`;
+    return url.origin;
 }
 export function oauthAuthorizationServerUrl(origin) {
     return new URL(OAUTH_AUTHORIZATION_SERVER_PATH, origin).toString();
@@ -50,11 +84,8 @@ export function oauthTokenEndpointUrl(origin) {
     return new URL(`${OAUTH_AUTHORIZATION_SERVER_PATH}/oauth2/token`, origin).toString();
 }
 export function oauthResourceKeyForPathname(pathname) {
-    if (pathname === OAUTH_RESOURCE_PATHS.mcp) {
-        return "mcp";
-    }
-    if (pathname === OAUTH_RESOURCE_PATHS.api ||
-        pathname.startsWith(`${OAUTH_RESOURCE_PATHS.api}/`)) {
+    if (pathname === OAUTH_API_RESOURCE_PATH ||
+        pathname.startsWith(`${OAUTH_API_RESOURCE_PATH}/`)) {
         return "api";
     }
     return null;