@every-app/sdk 0.2.0 → 0.3.0-rc.2

package/dist/internal/signInProviders.js

@@ -0,0 +1,238 @@
+/**
+ * The sign-in providers a Gateway can offer beside passwords ("Continue
+ * with Google"), as data: what each one is called, the Worker secrets it
+ * reads, where the OAuth app is made, the scopes asked for and which claim
+ * becomes the email. One catalog serves the Gateway (which providers are
+ * on, the sign-in page's buttons, Manage workspace → Sign-in), the CLI
+ * (`everyapp signin add|list|show|remove`, `secret set`), the manifest
+ * validator (an app's own secret can never take one of these names) and
+ * the docs' drift tests.
+ *
+ * Naming rule, agreed with the provider registry's conventions
+ * (docs/design/2026-10-provider-registry.md, section 6): a sign-in
+ * provider's settings are `<ID>_SIGNIN_<FIELD>`, with FIELD one of
+ * CLIENT_ID, CLIENT_SECRET, ISSUER, LABEL or TENANT. The `_SIGNIN_` infix is
+ * what keeps the family apart from the API providers' `<ID>_API_KEY`,
+ * `<ID>_CLIENT_ID` (the OAuth clients the Gateway holds for apps) and the
+ * MCP apps' `<ID>_MCP_TOKEN`: `GOOGLE_SIGNIN_CLIENT_ID` is the sign-in
+ * provider's, `GOOGLE_WORKSPACE_CLIENT_ID` the OAuth client apps use, and
+ * a registered provider row or an app manifest can never claim a name in
+ * the family (isSignInSettingName).
+ *
+ * The settings are Worker secrets, set under the Cloudflare login (`everyapp
+ * signin add`, or `secret set`), never from the admin UI or an agent
+ * connection: a stolen session can't add a way in.
+ */
+export const SIGN_IN_PROVIDER_IDS = [
+    "google",
+    "microsoft",
+    "github",
+    "apple",
+    "cloudflare",
+    "oidc",
+];
+/** The path Better Auth serves the provider's callback on, under the Gateway's URL. */
+export function signInCallbackPath(id) {
+    return `/api/auth/callback/${id}`;
+}
+/** The redirect URL to register with the provider, for a Gateway at `gatewayUrl`. */
+export function signInCallbackUrl(gatewayUrl, id) {
+    return `${gatewayUrl.replace(/\/+$/, "")}${signInCallbackPath(id)}`;
+}
+function settingName(id, field) {
+    return `${id.toUpperCase()}_SIGNIN_${field}`;
+}
+function clientPair(id, what) {
+    return [
+        {
+            name: settingName(id, "CLIENT_ID"),
+            role: "clientId",
+            required: true,
+            plain: true,
+            what: what.clientId,
+        },
+        {
+            name: settingName(id, "CLIENT_SECRET"),
+            role: "clientSecret",
+            required: true,
+            plain: false,
+            what: what.clientSecret,
+        },
+    ];
+}
+const IDENTITY_SCOPES = ["openid", "email", "profile"];
+export const SIGN_IN_PROVIDERS = {
+    google: {
+        id: "google",
+        label: "Google",
+        console: "https://console.cloud.google.com/apis/credentials",
+        appNoun: "OAuth client ID (Web application)",
+        settings: clientPair("google", {
+            clientId: "The OAuth client's Client ID (ends in .apps.googleusercontent.com)",
+            clientSecret: "The OAuth client's Client secret",
+        }),
+        scopes: IDENTITY_SCOPES,
+        emailClaim: "the ID token's `email`, counted as verified only when its `email_verified` is true (every Google account's own address is)",
+        setup: "setup/signin-google.md",
+        notes: [
+            "An OAuth consent screen still in Testing only signs in the test users listed on it; publish it for everyone else.",
+        ],
+    },
+    microsoft: {
+        id: "microsoft",
+        label: "Microsoft",
+        console: "https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade",
+        appNoun: "App registration",
+        settings: [
+            ...clientPair("microsoft", {
+                clientId: "The app registration's Application (client) ID",
+                clientSecret: "A client secret from Certificates & secrets (it expires; 24 months at most)",
+            }),
+            {
+                name: settingName("microsoft", "TENANT"),
+                role: "tenant",
+                required: false,
+                plain: true,
+                what: "The Directory (tenant) ID to pin sign-in to your own directory; unset means any Microsoft account (common), which then needs the xms_edov claim",
+            },
+        ],
+        scopes: IDENTITY_SCOPES,
+        emailClaim: "the ID token's `email`, counted as verified when MICROSOFT_SIGNIN_TENANT pins your own directory, or the token carries `xms_edov: true` (the optional claim that says the domain's owner verified it), `email_verified: true`, a matching `verified_primary_email`, or comes from a personal Microsoft account",
+        setup: "setup/signin-microsoft.md",
+        notes: [
+            "Without MICROSOFT_SIGNIN_TENANT, add the optional claims `email` and `xms_edov` under Token configuration, or every sign-in is refused as unverified: any tenant's admin can put any address on their users.",
+        ],
+    },
+    github: {
+        id: "github",
+        label: "GitHub",
+        console: "https://github.com/settings/developers",
+        appNoun: "OAuth App",
+        settings: clientPair("github", {
+            clientId: "The OAuth App's Client ID",
+            clientSecret: "A client secret generated on the OAuth App",
+        }),
+        scopes: ["read:user", "user:email"],
+        emailClaim: "the primary address from GitHub's emails API, counted as verified only when GitHub marks it verified",
+        setup: "setup/signin-github.md",
+        notes: [
+            "GitHub Apps are something else: make an OAuth App (Settings → Developer settings → OAuth Apps).",
+        ],
+    },
+    apple: {
+        id: "apple",
+        label: "Apple",
+        console: "https://developer.apple.com/account/resources/identifiers/list/serviceId",
+        appNoun: "Services ID",
+        settings: clientPair("apple", {
+            clientId: "The Services ID's identifier (com.example.gateway)",
+            clientSecret: "The client secret JWT you generate from your Sign in with Apple key (ES256; valid six months at most, then generate it again)",
+        }),
+        scopes: ["email", "name"],
+        emailClaim: "the ID token's `email`, counted as verified only when its `email_verified` is true; someone who chose Hide My Email arrives as a @privaterelay.appleid.com address, which no invitation names",
+        setup: "setup/signin-apple.md",
+        notes: [
+            "Apple returns to the Gateway with a POST; behind the outer ring, `everyapp access on` leaves /api/auth/callback/apple public (it only redirects to the same URL as a GET, which Access then checks).",
+            "The client secret is a JWT that expires within six months: generate a new one before then or sign-in stops.",
+        ],
+    },
+    cloudflare: {
+        id: "cloudflare",
+        label: "Cloudflare",
+        console: "https://dash.cloudflare.com/?to=/:account/oauth-clients",
+        appNoun: "OAuth client (Manage Account → OAuth clients)",
+        settings: clientPair("cloudflare", {
+            clientId: "The OAuth client's Client ID",
+            clientSecret: "The OAuth client's Client secret",
+        }),
+        scopes: ["user-details.read"],
+        emailClaim: "the Cloudflare API's /user `email` (the account's sign-in address). Cloudflare reports no verified flag, so the email counts as verified on the strength of the client being private: only members of your Cloudflare account can authorize it, and they got in by accepting an invitation sent to that address",
+        setup: "setup/signin-cloudflare.md",
+        notes: [
+            "Keep the client private (the default): a public client lets any Cloudflare user sign in, and Cloudflare says nothing about whether their address is verified. Making a client public is permanent.",
+            "The Cloudflare account's members sign in; for everyone else use Cloudflare Access's one-time PIN (`everyapp access on`) or another provider.",
+        ],
+    },
+    oidc: {
+        id: "oidc",
+        label: "SSO",
+        console: "your identity provider's admin console",
+        appNoun: "OpenID Connect client (web application, authorization code)",
+        settings: [
+            {
+                name: settingName("oidc", "ISSUER"),
+                role: "issuer",
+                required: true,
+                plain: true,
+                what: "The issuer URL (https://…), which serves /.well-known/openid-configuration",
+            },
+            ...clientPair("oidc", {
+                clientId: "The client ID",
+                clientSecret: "The client secret",
+            }),
+            {
+                name: settingName("oidc", "LABEL"),
+                role: "label",
+                required: false,
+                plain: true,
+                what: 'The button text after "Continue with" (default "SSO")',
+            },
+        ],
+        scopes: IDENTITY_SCOPES,
+        emailClaim: "the ID token's `email` (else the userinfo endpoint's), counted as verified only when `email_verified` is true",
+        setup: "setup/signin-oidc.md",
+        notes: [
+            "Cloudflare Access has its own settings (CLOUDFLARE_ACCESS_OIDC_*, `everyapp access`): use those for Access, this for Okta, Entra ID, Google Workspace as an OIDC issuer, Keycloak, Auth0 and the like.",
+            "ID tokens must be signed with RS256 (every major provider's default).",
+        ],
+    },
+};
+/** The catalog in listing order. */
+export const SIGN_IN_PROVIDER_LIST = SIGN_IN_PROVIDER_IDS.map((id) => SIGN_IN_PROVIDERS[id]);
+export function isSignInProviderId(value) {
+    return SIGN_IN_PROVIDER_IDS.includes(value);
+}
+/**
+ * Every setting a sign-in provider reads, in catalog order: what `everyapp
+ * secret set` accepts for the Gateway, and what the Gateway's dev config
+ * declares.
+ */
+export const SIGN_IN_GATEWAY_SETTINGS = SIGN_IN_PROVIDER_LIST.flatMap((provider) => provider.settings.map((setting) => setting.name));
+/** The plain (non-credential) ones among them: ids, the issuer, the label, the tenant. */
+export const PLAIN_SIGN_IN_SETTINGS = SIGN_IN_PROVIDER_LIST.flatMap((provider) => provider.settings
+    .filter((setting) => setting.plain)
+    .map((setting) => setting.name));
+/**
+ * The family: any name of the shape `<ID>_SIGNIN_<FIELD>`. Reserved for the
+ * catalog above, whether or not an entry reads the name today, so no
+ * registered provider row and no app manifest can ever take one.
+ */
+export const SIGN_IN_SETTING_PATTERN = /^[A-Z][A-Z0-9_]*_SIGNIN_(CLIENT_ID|CLIENT_SECRET|ISSUER|LABEL|TENANT)$/;
+export function isSignInSettingName(name) {
+    return SIGN_IN_SETTING_PATTERN.test(name);
+}
+/** The provider a setting belongs to, if one reads it. */
+export function signInProviderOfSetting(name) {
+    for (const provider of SIGN_IN_PROVIDER_LIST) {
+        if (provider.settings.some((setting) => setting.name === name)) {
+            return provider;
+        }
+    }
+    return null;
+}
+/**
+ * A provider's state from which of its settings exist: on when every
+ * required one is set, off when none at all is, incomplete in between (the
+ * Gateway refuses to half-configure a sign-in: the provider is off and the
+ * problem is reported).
+ */
+export function signInProviderState(provider, isSet) {
+    const set = provider.settings
+        .filter((setting) => isSet(setting.name))
+        .map((setting) => setting.name);
+    const missing = provider.settings
+        .filter((setting) => setting.required && !isSet(setting.name))
+        .map((setting) => setting.name);
+    const status = missing.length === 0 ? "on" : set.length === 0 ? "off" : "incomplete";
+    return { id: provider.id, status, missing, set };
+}

package/dist/internal/tools.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The internal tools contract (v1) between the gateway's ToolBus and an app's
+ * `everyApp()` wrapper. Two reserved endpoints, reached only over the
+ * gateway's service binding and never public:
+ *
+ *   POST /__everyapp/tools/list  x-everyapp-system JWT (purpose "tools.list")
+ *   POST /__everyapp/tools/call  x-everyapp-identity JWT, chan "mcp" + tc claim
+ *
+ * MCP itself (protocol eras, headers, envelopes) stays in the gateway; apps
+ * only ever speak this small versioned JSON shape. Both sides import the
+ * shapes, paths and the catalog hash from here so they cannot drift.
+ */
+export declare const TOOLS_PROTOCOL_VERSION = 1;
+export declare const TOOLS_PATH_PREFIX = "/__everyapp/tools";
+export declare const TOOLS_LIST_PATH = "/__everyapp/tools/list";
+export declare const TOOLS_CALL_PATH = "/__everyapp/tools/call";
+export declare const TOOL_RISKS: readonly ["read", "write", "destructive"];
+export type ToolRisk = (typeof TOOL_RISKS)[number];
+/** Scopes the gateway mints on `chan: "mcp"` identities, one per risk. */
+export declare const MCP_READ_SCOPE = "mcp:read";
+export declare const MCP_WRITE_SCOPE = "mcp:write";
+/** Never minted in v1: destructive tools are hidden until approvals exist. */
+export declare const MCP_DESTRUCTIVE_SCOPE = "mcp:destructive";
+/** Local tool names: lowercase snake_case, at most 48 characters. */
+export declare const TOOL_NAME_PATTERN: RegExp;
+export declare function isToolRisk(value: unknown): value is ToolRisk;
+/** The exact scope a `chan: "mcp"` identity must carry to call a tool. */
+export declare function requiredScopeForRisk(risk: ToolRisk): string;
+export interface ToolAnnotationsV1 {
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+/** One tool as an app describes it to the gateway. */
+export interface ToolDescriptorV1 {
+    name: string;
+    title?: string;
+    description: string;
+    risk: ToolRisk;
+    /** JSON Schema (draft 2020-12) of the arguments; always `type: "object"`. */
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations?: ToolAnnotationsV1;
+}
+export interface ToolsListRequestV1 {
+    v: 1;
+}
+export interface ToolsListResponseV1 {
+    v: 1;
+    /** The SDK version that produced the catalog. */
+    sdk: string;
+    /** {@link catalogHash} of `instructions` + `tools`. */
+    hash: string;
+    instructions?: string;
+    tools: ToolDescriptorV1[];
+    /** Tools the SDK left out because it can't describe them, and why. */
+    warnings?: string[];
+}
+/** The `tc` identity claim: binds a `chan: "mcp"` token to one call. */
+export interface ToolCallClaim {
+    id: string;
+    name: string;
+}
+export interface ToolsCallRequestV1 {
+    v: 1;
+    name: string;
+    arguments: Record<string, unknown>;
+    /** Must equal the identity token's `tc.id`. */
+    callId: string;
+}
+export interface ToolContentBlockV1 {
+    type: string;
+    [key: string]: unknown;
+}
+export interface ToolCallResultV1 {
+    content: ToolContentBlockV1[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+export type ToolsErrorCodeV1 = "unknown_tool" | "invalid_arguments" | "invalid_request" | "forbidden" | "unauthenticated" | "method_not_allowed" | "misconfigured";
+export interface ToolIssueV1 {
+    message: string;
+    path?: (string | number)[];
+}
+export interface ToolsErrorV1 {
+    code: ToolsErrorCodeV1;
+    message: string;
+    issues?: ToolIssueV1[];
+}
+export interface ToolsCallSuccessV1 {
+    v: 1;
+    /** The app's current catalog hash; the gateway re-syncs on a mismatch. */
+    catalogHash: string;
+    result: ToolCallResultV1;
+}
+export interface ToolsErrorResponseV1 {
+    v: 1;
+    error: ToolsErrorV1;
+}
+export type ToolsCallResponseV1 = ToolsCallSuccessV1 | ToolsErrorResponseV1;
+/**
+ * JSON with object keys sorted at every depth, so equal values always
+ * serialize identically. `undefined` members are dropped, as JSON.stringify
+ * does.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * `sha256:<hex>` over the canonical JSON of a catalog. The SDK reports it with
+ * every list and call; the gateway stores it at sync and re-syncs when a call
+ * reports a different one.
+ */
+export declare function catalogHash(catalog: {
+    instructions?: string;
+    tools: readonly ToolDescriptorV1[];
+}): Promise<string>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/internal/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/internal/tools.ts"],"names":[],"mappings":"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"}

package/dist/internal/tools.js

@@ -0,0 +1,80 @@
+/**
+ * The internal tools contract (v1) between the gateway's ToolBus and an app's
+ * `everyApp()` wrapper. Two reserved endpoints, reached only over the
+ * gateway's service binding and never public:
+ *
+ *   POST /__everyapp/tools/list  x-everyapp-system JWT (purpose "tools.list")
+ *   POST /__everyapp/tools/call  x-everyapp-identity JWT, chan "mcp" + tc claim
+ *
+ * MCP itself (protocol eras, headers, envelopes) stays in the gateway; apps
+ * only ever speak this small versioned JSON shape. Both sides import the
+ * shapes, paths and the catalog hash from here so they cannot drift.
+ */
+export const TOOLS_PROTOCOL_VERSION = 1;
+export const TOOLS_PATH_PREFIX = "/__everyapp/tools";
+export const TOOLS_LIST_PATH = `${TOOLS_PATH_PREFIX}/list`;
+export const TOOLS_CALL_PATH = `${TOOLS_PATH_PREFIX}/call`;
+export const TOOL_RISKS = ["read", "write", "destructive"];
+/** Scopes the gateway mints on `chan: "mcp"` identities, one per risk. */
+export const MCP_READ_SCOPE = "mcp:read";
+export const MCP_WRITE_SCOPE = "mcp:write";
+/** Never minted in v1: destructive tools are hidden until approvals exist. */
+export const MCP_DESTRUCTIVE_SCOPE = "mcp:destructive";
+/** Local tool names: lowercase snake_case, at most 48 characters. */
+export const TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]{0,47}$/;
+export function isToolRisk(value) {
+    return (typeof value === "string" &&
+        TOOL_RISKS.includes(value));
+}
+/** The exact scope a `chan: "mcp"` identity must carry to call a tool. */
+export function requiredScopeForRisk(risk) {
+    switch (risk) {
+        case "read":
+            return MCP_READ_SCOPE;
+        case "write":
+            return MCP_WRITE_SCOPE;
+        case "destructive":
+            return MCP_DESTRUCTIVE_SCOPE;
+    }
+}
+/**
+ * JSON with object keys sorted at every depth, so equal values always
+ * serialize identically. `undefined` members are dropped, as JSON.stringify
+ * does.
+ */
+export function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (!value || typeof value !== "object")
+        return value;
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+        const member = value[key];
+        if (member !== undefined)
+            sorted[key] = sortKeys(member);
+    }
+    return sorted;
+}
+/**
+ * `sha256:<hex>` over the canonical JSON of a catalog. The SDK reports it with
+ * every list and call; the gateway stores it at sync and re-syncs when a call
+ * reports a different one.
+ */
+export async function catalogHash(catalog) {
+    const canonical = canonicalJson({
+        instructions: catalog.instructions ?? null,
+        tools: catalog.tools,
+    });
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical));
+    return `sha256:${toHex(digest)}`;
+}
+function toHex(buffer) {
+    let out = "";
+    for (const byte of new Uint8Array(buffer)) {
+        out += byte.toString(16).padStart(2, "0");
+    }
+    return out;
+}

package/dist/server/attribution.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Whom a call through the gateway is for, which decides the organization
+ * it counts against:
+ *
+ *  - the inbound `Request`: its person, by the identity the gateway put on
+ *    it (forwarded as is);
+ *  - `{ background: true, organizationId }`: work no request started (a
+ *    cron, a Workflow step, a queue). A shared app's Worker serves every
+ *    organization, so it names the one the work is for, which the gateway
+ *    checks is active and has a live member. An organization's own app may
+ *    leave it out (the gateway knows its organization) and may only name
+ *    its own.
+ */
+export type GatewayCallFor = Request | {
+    background: true;
+    organizationId?: string;
+};
+/**
+ * A gateway call that doesn't say whom it is for where it must: from a
+ * shared app's Worker, with neither the request nor an organization.
+ */
+export declare class AttributionError extends Error {
+    readonly code = "attribution_required";
+    constructor(message: string);
+}
+/**
+ * Check `target` before any call is made: a shared app's Worker must pass
+ * the request or name the organization, and anything else passed must be
+ * one of the two shapes.
+ */
+export declare function checkAttribution(env: object, target: GatewayCallFor | undefined, what: string): void;
+/**
+ * Put the call's attribution on its headers: the request's identity, or the
+ * background work's organization, and never one the app set itself.
+ */
+export declare function applyAttribution(headers: Headers, target: GatewayCallFor | undefined): void;
+/** Whether `for` is the inbound request (rather than background work). */
+export declare function isRequest(value: unknown): value is Request;
+//# sourceMappingURL=attribution.d.ts.map

package/dist/server/attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../../src/server/attribution.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GACtB,OAAO,GACP;IAAE,UAAU,EAAE,IAAI,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,0BAA0B;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,GACX,IAAI,CAsBN;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,cAAc,GAAG,SAAS,GACjC,IAAI,CAUN;AASD,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAO1D"}

package/dist/server/attribution.js

@@ -0,0 +1,67 @@
+import { IDENTITY_HEADER, ORG_HEADER, SHARED_ENV } from "../internal/index.js";
+/**
+ * A gateway call that doesn't say whom it is for where it must: from a
+ * shared app's Worker, with neither the request nor an organization.
+ */
+export class AttributionError extends Error {
+    code = "attribution_required";
+    constructor(message) {
+        super(message);
+        this.name = "AttributionError";
+    }
+}
+/**
+ * Check `target` before any call is made: a shared app's Worker must pass
+ * the request or name the organization, and anything else passed must be
+ * one of the two shapes.
+ */
+export function checkAttribution(env, target, what) {
+    if (target !== undefined && !isRequest(target)) {
+        if (target === null || typeof target !== "object" || !target.background) {
+            throw new AttributionError(`${what}: \`for\` is the inbound Request or { background: true, organizationId }.`);
+        }
+        if (target.organizationId !== undefined &&
+            !nonEmpty(target.organizationId)) {
+            throw new AttributionError(`${what}: { background: true, organizationId } needs a non-empty organization id.`);
+        }
+    }
+    if (!isSharedWorker(env))
+        return;
+    if (target === undefined || (!isRequest(target) && !target.organizationId)) {
+        throw new AttributionError(`${what} in a shared app's Worker serves every organization, so it must say whom the call is for: for: request, or for: { background: true, organizationId } for work no request started.`);
+    }
+}
+/**
+ * Put the call's attribution on its headers: the request's identity, or the
+ * background work's organization, and never one the app set itself.
+ */
+export function applyAttribution(headers, target) {
+    headers.delete(IDENTITY_HEADER);
+    headers.delete(ORG_HEADER);
+    if (target === undefined)
+        return;
+    if (isRequest(target)) {
+        const identity = target.headers.get(IDENTITY_HEADER);
+        if (identity)
+            headers.set(IDENTITY_HEADER, identity);
+        return;
+    }
+    if (target.organizationId)
+        headers.set(ORG_HEADER, target.organizationId);
+}
+function isSharedWorker(env) {
+    const value = env[SHARED_ENV];
+    return value === "1" || value === "true" || value === true;
+}
+// Duck-typed: a Request from another realm (a test runner, a polyfill) is
+// still the request.
+/** Whether `for` is the inbound request (rather than background work). */
+export function isRequest(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "headers" in value &&
+        typeof value.headers?.get === "function");
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}

package/dist/server/authorizeUrl.d.ts

@@ -0,0 +1,43 @@
+import { type OAuthClientCapabilityId } from "../internal/index.js";
+import type { OAuthClientIntegrationStatus } from "./integrationFetch.js";
+export interface AuthorizeUrlOptions {
+    /** The OAuth client, as listed in the manifest's `capabilities`. */
+    provider: OAuthClientCapabilityId;
+    /** What `integrationStatus()` answered for it, ready and with its `clientId`. */
+    status: OAuthClientIntegrationStatus;
+    /** One of the redirect URIs the operator registered on the client. */
+    redirectUri: string;
+    /** The app's own anti-forgery value, checked when the person comes back. */
+    state: string;
+    /** PKCE: the S256 challenge of the verifier the app keeps for the exchange. */
+    codeChallenge?: string;
+    /**
+     * The provider's extras (`prompt`, `login_hint`, Google's `hd`). Never
+     * one of the parameters this helper sets (PKCE's and the provider's own
+     * included), nor Google's `include_granted_scopes`.
+     */
+    params?: Record<string, string>;
+}
+/**
+ * The provider's authorize URL to send a person to, for a client with
+ * scope sets (`google-workspace`, `microsoft-365`, `slack`), built from the
+ * capability's status: the registry's authorize endpoint (or the instance
+ * the status names), `client_id`, `response_type=code`, `redirect_uri`,
+ * `state`, and the scopes the status allows this app, which are exactly
+ * what the gateway will let the token carry. Each provider's own needs
+ * are added: Google's `access_type=offline` (a refresh token), Microsoft's
+ * `response_mode=query`, Slack's comma-joined `scope` and its `user_scope`
+ * (the status's `userScopes`, when the app's sets include a user set). With
+ * `codeChallenge`, PKCE as S256. The app keeps its `state` and verifier
+ * for the callback.
+ *
+ * A client without scope sets (LinkedIn, Mastodon, ...) is refused: the
+ * registry's checklist for one isn't what the gateway holds a token to,
+ * so an app builds that URL itself from the status's `clientId`.
+ *
+ * Throws a `TypeError` naming the fix when the client has no scope sets,
+ * when the status isn't ready or has no `clientId`, when the status lacks
+ * `scopes`, or when `params` names a parameter the helper sets.
+ */
+export declare function authorizeUrl({ provider, status, redirectUri, state, codeChallenge, params, }: AuthorizeUrlOptions): URL;
+//# sourceMappingURL=authorizeUrl.d.ts.map

package/dist/server/authorizeUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorizeUrl.d.ts","sourceRoot":"","sources":["../../src/server/authorizeUrl.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,QAAQ,EAAE,uBAAuB,CAAC;IAClC,iFAAiF;IACjF,MAAM,EAAE,4BAA4B,CAAC;IACrC,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAgCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,MAAM,EACN,WAAW,EACX,KAAK,EACL,aAAa,EACb,MAAM,GACP,EAAE,mBAAmB,GAAG,GAAG,CA2D3B"}