@spacefast/common 0.0.26 → 0.2.2

package/dist/agents/private-key-oauth.js

@@ -1,57 +1,92 @@
 import { webcrypto } from "node:crypto";
 import * as oauth from "oauth4webapi";
+import { z } from "zod";
 import { OAUTH_API_RESOURCE_SCOPES, oauthApiResourceUrl } from "../contracts/oauth-resources.js";
 const API_RESOURCE_SCOPES = new Set(OAUTH_API_RESOURCE_SCOPES);
 const INVALID_PRIVATE_KEY_MESSAGE = "SPACEFAST_AGENT_CONFIG private_jwk must be an ES256 P-256 JWK.";
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function isJwkObject(value) {
-    // Keep parsing permissive here. Web Crypto remains the authority on the JWK's
-    // individual fields, matching the callers' previous behavior.
-    return value !== null && typeof value === "object";
-}
-function readJsonObject(value) {
+const parsedAgentPrivateJwkSchema = z.object({
+    alg: z.string().optional(),
+    crv: z.string().optional(),
+    d: z.string().optional(),
+    ext: z.boolean().optional(),
+    key_ops: z.array(z.string()).optional(),
+    kid: z.string().optional(),
+    kty: z.string().optional(),
+    use: z.string().optional(),
+    x: z.string().optional(),
+    y: z.string().optional(),
+});
+const agentPrivateJwkSchema = parsedAgentPrivateJwkSchema.transform((parsed) => {
+    const jwk = {};
+    if (parsed.alg !== undefined)
+        jwk.alg = parsed.alg;
+    if (parsed.crv !== undefined)
+        jwk.crv = parsed.crv;
+    if (parsed.d !== undefined)
+        jwk.d = parsed.d;
+    if (parsed.ext !== undefined)
+        jwk.ext = parsed.ext;
+    if (parsed.key_ops !== undefined)
+        jwk.key_ops = parsed.key_ops;
+    if (parsed.kid !== undefined)
+        jwk.kid = parsed.kid;
+    if (parsed.kty !== undefined)
+        jwk.kty = parsed.kty;
+    if (parsed.use !== undefined)
+        jwk.use = parsed.use;
+    if (parsed.x !== undefined)
+        jwk.x = parsed.x;
+    if (parsed.y !== undefined)
+        jwk.y = parsed.y;
+    return jwk;
+});
+const bundledAgentAuthConfigSchema = z.object({
+    client_id: z.string().optional(),
+    token_endpoint: z.string().optional(),
+    private_jwk: agentPrivateJwkSchema.optional(),
+    scope: z.string().optional(),
+    resources: z.array(z.string()).optional(),
+});
+function readBundledAgentAuthConfig(value) {
     if (!value?.trim()) {
         return null;
     }
-    const parsed = JSON.parse(value);
-    return isRecord(parsed) ? parsed : null;
+    return bundledAgentAuthConfigSchema.parse(JSON.parse(value));
 }
-function stringArray(value) {
-    return Array.isArray(value)
-        ? value.filter((entry) => typeof entry === "string")
-        : undefined;
+function readPrivateJwk(value) {
+    if (!value?.trim()) {
+        return null;
+    }
+    return agentPrivateJwkSchema.parse(JSON.parse(value));
 }
-/** Parse private-key agent credentials using the established bundled-over-split env precedence. */
+/** Parse private-key agent credentials using the bundled-over-split env precedence. */
 export function readAgentAuthConfig(env, apiUrl) {
-    const bundled = readJsonObject(env.SPACEFAST_AGENT_CONFIG);
-    const bundledPrivateJwk = bundled?.private_jwk;
-    const privateJwk = isJwkObject(bundledPrivateJwk)
-        ? bundledPrivateJwk
-        : readJsonObject(env.SPACEFAST_AGENT_PRIVATE_JWK);
-    const clientId = (typeof bundled?.client_id === "string" ? bundled.client_id : undefined) ??
-        env.SPACEFAST_AGENT_CLIENT_ID;
+    const bundled = readBundledAgentAuthConfig(env.SPACEFAST_AGENT_CONFIG);
+    const privateJwk = bundled?.private_jwk ?? readPrivateJwk(env.SPACEFAST_AGENT_PRIVATE_JWK);
+    const clientId = bundled?.client_id ?? env.SPACEFAST_AGENT_CLIENT_ID;
     if (!clientId || !privateJwk) {
         return null;
     }
-    const tokenEndpoint = (typeof bundled?.token_endpoint === "string" ? bundled.token_endpoint : undefined) ??
+    const tokenEndpoint = bundled?.token_endpoint ??
         env.SPACEFAST_AGENT_TOKEN_ENDPOINT ??
         `${apiUrl}/v1/auth/oauth2/token`;
-    const scope = (typeof bundled?.scope === "string" ? bundled.scope : undefined) ?? env.SPACEFAST_AGENT_SCOPE;
-    const resources = stringArray(bundled?.resources) ??
+    const scope = bundled?.scope ?? env.SPACEFAST_AGENT_SCOPE;
+    const resources = bundled?.resources ??
         (env.SPACEFAST_AGENT_RESOURCES
             ? env.SPACEFAST_AGENT_RESOURCES.split(",")
                 .map((entry) => entry.trim())
                 .filter(Boolean)
             : undefined);
-    return {
+    const config = {
         client_id: clientId,
         token_endpoint: tokenEndpoint,
         private_jwk: privateJwk,
-        ...(scope ? { scope } : {}),
-        ...(resources?.length ? { resources } : {}),
     };
+    if (scope)
+        config.scope = scope;
+    if (resources?.length)
+        config.resources = resources;
+    return config;
 }
 export function resolveAgentApiAuthorization(config, apiUrl) {
     const configuredResources = config.resources;
@@ -81,10 +116,10 @@ async function privateKeyJwtClientAuth(config, createInvalidConfigError = (messa
     }
     try {
         const key = await webcrypto.subtle.importKey("jwk", config.private_jwk, { name: "ECDSA", namedCurve: "P-256" }, false, ["sign"]);
-        return oauth.PrivateKeyJwt({
-            key,
-            ...(config.private_jwk.kid ? { kid: config.private_jwk.kid } : {}),
-        });
+        if (config.private_jwk.kid) {
+            return oauth.PrivateKeyJwt({ key, kid: config.private_jwk.kid });
+        }
+        return oauth.PrivateKeyJwt({ key });
     }
     catch {
         throw createInvalidConfigError(INVALID_PRIVATE_KEY_MESSAGE);
@@ -139,3 +174,59 @@ export async function exchangeAgentAccessToken(input) {
     }
     return { accessToken: tokens.access_token, expiresIn: tokens.expires_in ?? 300 };
 }
+/**
+ * Refresh margin: a token this close to expiry is treated as already gone, so a
+ * request never leaves with a credential that dies in flight.
+ */
+const TOKEN_EXPIRY_SKEW_MS = 30_000;
+/**
+ * One agent access token held across calls instead of re-exchanged per request.
+ *
+ * The client-credentials grant is a signed round trip to the token endpoint, and
+ * an agent identity issues the same token for the same authorization until it
+ * expires: paying for it on every command (the CLI) or every tool call (the MCP
+ * server) buys nothing. The cache key is the authorization itself — client,
+ * endpoint, and the scope/resources {@link resolveAgentApiAuthorization} settled
+ * on — so pointing a process at a second API never replays the first one's
+ * bearer.
+ */
+export function createCachedAgentTokenProvider(options) {
+    const now = options.now ?? (() => Date.now());
+    let cached = null;
+    return {
+        async accessToken(request) {
+            const { resources, scope } = resolveAgentApiAuthorization(request.config, request.apiUrl);
+            const key = JSON.stringify({
+                client_id: request.config.client_id,
+                token_endpoint: request.config.token_endpoint,
+                scope,
+                resources,
+            });
+            if (cached?.key === key && cached.expiresAtMs > now() + TOKEN_EXPIRY_SKEW_MS) {
+                return cached.accessToken;
+            }
+            const exchangeInput = {
+                apiUrl: request.apiUrl,
+                client: request.client,
+                config: request.config,
+                signal: request.signal,
+                createError: options.createError,
+            };
+            if (options.createInvalidConfigError) {
+                exchangeInput.createInvalidConfigError = options.createInvalidConfigError;
+            }
+            if (options.fetch)
+                exchangeInput.fetch = options.fetch;
+            const result = await exchangeAgentAccessToken(exchangeInput);
+            cached = {
+                key,
+                accessToken: result.accessToken,
+                expiresAtMs: now() + result.expiresIn * 1_000,
+            };
+            return result.accessToken;
+        },
+        invalidate() {
+            cached = null;
+        },
+    };
+}

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

@@ -0,0 +1,292 @@
+/**
+ * Canonical, browser-safe agent integration registry.
+ *
+ * Keep this module free of Node built-ins, filesystem access, and environment
+ * reads. Runtime-specific path and config mechanics live in ./node.ts.
+ */
+export declare const AGENT_IDS: readonly ["claude-code", "claude-app", "claude-desktop", "cursor", "codex", "chatgpt", "vscode", "github-copilot", "devin-desktop", "devin-cloud", "zed", "gemini-cli", "opencode", "amp", "warp", "factory-droid", "cline", "continue", "raycast", "poke", "pi", "indent", "hermes", "openclaw"];
+export declare const SKILLS_CLI_PACKAGE_SPEC = "skills";
+export declare const SPACEFAST_CLI_PACKAGE_SPEC = "spacefast";
+export declare const PLUGINS_CLI_PACKAGE_SPEC = "plugins";
+/**
+ * The complete `-t` target set the universal plugin installer implements.
+ * Anything outside this list has no install
+ * mechanics upstream: `npx plugins add … -t <id>` either errors or synthesizes a
+ * manifest, so `sf plugins` must refuse it rather than run a command that cannot
+ * work. Capability flags are NOT a substitute — several entries carry a `plugin`
+ * capability because a vendor-native plugin lane exists, not because this
+ * installer can drive it.
+ */
+export declare const PLUGINS_CLI_INSTALLER_TARGETS: readonly ["claude-code", "cursor", "codex", "github-copilot", "vscode", "grok", "kimi"];
+export type PluginsCliInstallerTarget = (typeof PLUGINS_CLI_INSTALLER_TARGETS)[number];
+export declare const AGENT_DISTRIBUTION_PROFILE: {
+    readonly author: {
+        readonly name: "Automattic";
+        readonly url: "https://spacefast.com";
+    };
+    readonly description: "Spacefast publishes files and folders to permanent web URLs with immutable versions, scoped access, and resumable MCP workflows.";
+    readonly displayName: "Spacefast";
+    readonly homepage: "https://spacefast.com";
+    readonly keywords: readonly ["spacefast", "publish-to-spacefast", "artifact-sharing", "hosting"];
+    readonly license: "MIT";
+    readonly name: "spacefast";
+    readonly privacyPolicyUrl: "https://automattic.com/privacy/";
+    readonly repository: "https://github.com/spacefast/plugins";
+    readonly reviewerAccount: {
+        readonly environment: "marketplace-reviewers";
+        readonly secret: "SPACEFAST_REVIEWER_ACCOUNT";
+    };
+    readonly shortDescription: "Publish files and folders to the web instantly.";
+    readonly termsOfServiceUrl: "https://wordpress.com/tos/";
+};
+export type AgentId = (typeof AGENT_IDS)[number];
+export type AgentAlias = string;
+export type Platform = "darwin" | "linux" | "win32" | "web" | "ios" | "android";
+export type PresentationContext = "interactive-primary" | "terminal-alternates" | "static-docs" | "machine-installer";
+export type AgentCapability = "skills" | "mcp-local" | "mcp-oauth" | "plugin" | "deeplink-only" | "none";
+export type ListingStatus = "live" | "submitted" | "planned";
+export type SkillLane = "curl" | "mcp-only" | "plugin" | "cli";
+export type TokenClass = "api-key" | "handoff" | "oauth-access-token" | "plugin-secret";
+export type RegistryContext = Readonly<{
+    apiOrigin: string;
+    dashboardOrigin: string;
+    mcpEndpoint: string;
+    /** Override setup executables when a published artifact requires exact package versions. */
+    packageSpecs?: Readonly<{
+        skillsCli?: string;
+        spacefastCli?: string;
+    }>;
+    /**
+     * Origin that serves space git remotes. Optional so existing callers keep
+     * working; it falls back to this environment's push origin, which is what
+     * every caller would have passed anyway.
+     */
+    pushOrigin?: string;
+    token?: string;
+    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.
+ */
+export type RegistryVerificationStatus = "declared" | "probed" | "failed";
+export type RegistryVerification = Readonly<{
+    checkedAt: string;
+    evidence?: string;
+    sourceUrl: string;
+    status: RegistryVerificationStatus;
+}>;
+export type TokenSlot = Readonly<{
+    accepts: readonly TokenClass[];
+    location: "command" | "config-value" | "header";
+    placeholder: "{{token}}";
+}>;
+/**
+ * `checkedAt` is what stops a "soon" chip from aging silently (spec §8.2): the
+ * chip copy is date-free, so the age lives on the data and the release parity
+ * gate reports listing ages from here.
+ */
+export type MethodListing = Readonly<{
+    checkedAt: string;
+    status: ListingStatus;
+    url?: string;
+}>;
+type MethodBase = Readonly<{
+    authLane: "oauth" | "token-slot" | "anonymous";
+    availability: Readonly<{
+        clients: readonly AgentId[];
+        minClientVersion?: string;
+        platforms?: readonly Platform[];
+    }>;
+    docsUrl: string;
+    id: string;
+    label: string;
+    listing: MethodListing;
+    rank: Partial<Readonly<Record<PresentationContext, number>>>;
+    summary: string;
+    tokenSlot?: TokenSlot;
+    /** The vendor's own doc for this exact method, rendered beside the summary. */
+    vendorDocs?: Readonly<{
+        href: string;
+        label: string;
+    }>;
+    verification: RegistryVerification;
+}>;
+export type IntegrationMethod = MethodBase & (Readonly<{
+    authPolicy?: "on-install";
+    commands: Readonly<{
+        inSession: readonly string[];
+        shell: readonly string[];
+    }>;
+    /**
+     * Present only when the universal installer can actually drive
+     * this client. `sf plugins` and every rendered `npx plugins … -t` command
+     * gate on this, never on the `plugin` capability flag.
+     */
+    installerTargets?: readonly PluginsCliInstallerTarget[];
+    kind: "plugin";
+    marketplace?: Readonly<{
+        id: string;
+        url: string;
+    }>;
+}> | Readonly<{
+    badge?: Readonly<{
+        alt: string;
+        url: string;
+    }>;
+    build: (context: RegistryContext) => string;
+    /** Resolved against sibling methods at registry construction; never dangling. */
+    fallback: Readonly<{
+        id: string;
+        kind: IntegrationMethod["kind"];
+    }>;
+    kind: "deeplink";
+}> | Readonly<{
+    build: (context: RegistryContext) => readonly string[];
+    kind: "command";
+}> | Readonly<{
+    build: (context: RegistryContext) => string;
+    kind: "config";
+    /** `text` is a value pasted into a client's own settings form, not a file. */
+    language: "json" | "jsonc" | "text" | "toml" | "yaml";
+    path: string;
+}> | Readonly<{
+    build: (context: RegistryContext) => string;
+    kind: "prompt";
+}> | Readonly<{
+    kind: "download";
+    url: (context: RegistryContext) => string;
+}> | Readonly<{
+    kind: "skill";
+    lane: SkillLane;
+    source: Readonly<{
+        id: string;
+        url: string;
+    }>;
+}>);
+export type AgentEntry = Readonly<{
+    agentsMd: "native" | "opt-in" | "none";
+    aliases: readonly AgentAlias[];
+    capabilities: readonly AgentCapability[];
+    description: string;
+    detectionHints: readonly string[];
+    docs: Readonly<{
+        spacefast: string;
+        vendor: string;
+    }>;
+    icon: string;
+    id: AgentId;
+    kind: "coding-agent" | "chat-app" | "mcp-app" | "editor";
+    legacyResultAliases: readonly string[];
+    machineClient?: boolean;
+    methods: readonly IntegrationMethod[];
+    monogram: string;
+    name: string;
+    notes?: readonly string[];
+    redeemableClientTargetId?: AgentId;
+    skills: Readonly<{
+        agentsDirs: boolean;
+        claudeDirs: boolean;
+    }>;
+    tier: "featured" | "listed";
+    verification: RegistryVerification;
+    vendor: string;
+    wizardGroup: "claude" | "openai" | "coding-agents" | "personal-agents" | "mcp-apps" | "prompt-first" | null;
+}>;
+export type PresentedMethod = Readonly<{
+    /**
+     * `disabled` is the registry's own answer for a method that has nothing to
+     * copy yet (a planned marketplace listing whose install command does not exist).
+     * Consumers render the "soon" chip from this; they never gate on an empty string.
+     */
+    action: Readonly<{
+        kind: "copy" | "disabled" | "download" | "link";
+        label: string;
+        value: string;
+    }>;
+    docsUrl: string;
+    fallbackMethodId?: string;
+    id: string;
+    kind: IntegrationMethod["kind"];
+    label: string;
+    /** The fence language for `action.value`, so renderers never re-derive it. */
+    language: "bash" | "json" | "jsonc" | "text" | "toml" | "yaml";
+    listing: MethodListing;
+    /** Where the value goes: a config file path, or the client's own settings screen. */
+    path?: string;
+    rank: number;
+    summary: string;
+    vendorDocs?: Readonly<{
+        href: string;
+        label: string;
+    }>;
+}>;
+export type PresentedAgentEntry = Omit<AgentEntry, "methods"> & Readonly<{
+    methods: readonly PresentedMethod[];
+    /** The no-session, no-mint lane: docs pages and the machine artifacts. */
+    staticDocs: readonly PresentedMethod[];
+    terminalAlternates: readonly PresentedMethod[];
+}>;
+export declare const AGENTS_MD_SPACEFAST_START = "<!-- SPACEFAST START -->";
+export declare const AGENTS_MD_SPACEFAST_END = "<!-- SPACEFAST END -->";
+export declare const AGENTS_MD_SPACEFAST_SNIPPET: string;
+export declare const SOURCE_LANES: readonly [{
+    readonly id: "drop";
+    readonly label: "Drop files";
+    readonly description: "Drop a folder or archive and put it live now.";
+    readonly href: "/drop";
+    readonly icon: "upload";
+}, {
+    readonly id: "push";
+    readonly label: "Push directly";
+    readonly description: "Push a Git repository to Spacefast and publish every update.";
+    readonly href: "/push";
+    readonly icon: "git";
+}, {
+    readonly id: "github";
+    readonly label: "Connect a GitHub repository";
+    readonly description: "Connect GitHub and build and publish on every push.";
+    readonly href: "https://spacefast.com/docs/builds";
+    readonly icon: "github";
+}, {
+    readonly id: "terminal";
+    readonly label: "Command line";
+    readonly description: "Publish from the terminal with the Spacefast CLI.";
+    readonly href: "/start?step=terminal";
+    readonly icon: "terminal";
+}, {
+    readonly id: "api";
+    readonly label: "API";
+    readonly description: "Publish or automate with the REST API and OpenAPI.";
+    readonly href: "https://spacefast.com/docs/api";
+    readonly icon: "api";
+}];
+/**
+ * The generic hosted-MCP entry, for any client whose config is an `mcpServers`
+ * map. `type: "http"` is load-bearing and not decoration: Claude Code rejects a
+ * bare `{ url }` outright and VS Code reads one as a stdio command, so a bare
+ * url is not a smaller version of this — it is a broken version of it.
+ */
+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[];
+/**
+ * The `sf plugins` gate. Returns the universal-installer targets this agent can
+ * actually be installed into — empty for every agent whose plugin lane is
+ * vendor-native or not live, including entries that carry a `plugin` capability.
+ */
+export declare function pluginInstallerTargetsFor(agentId: AgentId): readonly PluginsCliInstallerTarget[];
+export declare function presentAgentEntry(agentId: AgentId, context: RegistryContext): PresentedAgentEntry;
+export declare function base64Utf8(value: string): string;
+export {};