@every-app/sdk 0.1.14 → 0.3.0-rc.1

package/dist/internal/gatewaySettings.js

@@ -0,0 +1,209 @@
+/**
+ * The Gateway's settings and the app's own secrets, by name: the Gateway
+ * settings an operator changes with `everyapp secret set <NAME>` (plain
+ * secrets on the Gateway Worker, read on its next request), the ones the
+ * install writes once, and the names an app's own secret can never take.
+ * What an app's manifest needs of them is appSettings.ts. One registry serves
+ * the CLI (a Gateway name goes to the Gateway, any other to the app in the
+ * current directory), the manifest validator (an app's `secrets` may not
+ * take a Gateway name, since the app reaches those through `providers` and
+ * `capabilities`) and the Gateway's dev config, which a test keeps
+ * declaring every settable one.
+ */
+import { CAPABILITIES, CAPABILITY_IDS, capabilitySettings, } from "./capabilities.js";
+/**
+ * The Gateway's own settings: the install writes them once (`everyapp
+ * setup`), or an operator by hand (THIRD_PARTY_DEPLOYS), and `everyapp
+ * secret set` never changes them. An app's own Worker may still have a
+ * secret of the same name (OpenSEO's BETTER_AUTH_SECRET): the two never meet.
+ */
+export const INSTALL_OWNED_GATEWAY_SETTINGS = [
+    "GATEWAY_URL",
+    "APP_BASE_DOMAIN",
+    "BETTER_AUTH_SECRET",
+    "JWT_PRIVATE_KEY",
+    "JWT_PUBLIC_KEY",
+    "GATEWAY_DEPLOYMENT_MODE",
+    "CLOUDFLARE_ACCOUNT_ID",
+    "THIRD_PARTY_DEPLOYS",
+];
+const INSTALL_OWNED = new Set(INSTALL_OWNED_GATEWAY_SETTINGS);
+export function isInstallOwnedGatewaySetting(name) {
+    return INSTALL_OWNED.has(name);
+}
+/**
+ * The settings the catalog's providers read (the AI providers' keys, the
+ * API-key providers' keys, the OAuth clients and the Mastodon instance's
+ * URL), in catalog order, the install's own left out: what `everyapp
+ * secret set` accepts because a provider reads it. A gateway's registered
+ * rows add theirs at run time (providerRegistry.settingNames()).
+ */
+const PROVIDER_GATEWAY_SETTINGS = [
+    ...new Set(CAPABILITY_IDS.flatMap((id) => {
+        const capability = CAPABILITIES[id];
+        return capability.mode === "service"
+            ? []
+            : capabilitySettings(capability);
+    })),
+].filter((name) => !INSTALL_OWNED.has(name));
+/** The Gateway's own optional settings `everyapp secret set` changes: nothing a provider reads. */
+export const GATEWAY_OWN_SETTINGS = [
+    "AI_PROXY_EXTRA_ROUTES",
+    // Email's providers: Cloudflare's REST token, Resend's key, the choice.
+    "EMAIL_REST_API_TOKEN",
+    "RESEND_API_KEY",
+    "EMAIL_PROVIDER",
+    "EMAIL_FROM",
+    "EMAIL_FROM_NAME",
+    "MCP_OAUTH_ENABLED",
+    "MCP_DCR_ENABLED",
+    "MCP_ALLOWED_ORIGINS",
+    "MCP_AUDIT_RETENTION_DAYS",
+    "CLOUDFLARE_ACCESS_OIDC_ISSUER",
+    "CLOUDFLARE_ACCESS_OIDC_CLIENT_ID",
+    "CLOUDFLARE_ACCESS_OIDC_CLIENT_SECRET",
+    "CLOUDFLARE_ACCESS_OIDC_LABEL",
+    "CLOUDFLARE_ACCESS_TEAM_DOMAIN",
+    "CLOUDFLARE_ACCESS_AUD",
+    "CLOUDFLARE_ACCESS_APPS_AUD",
+    "CLOUDFLARE_ACCESS_AUTO_JOIN_DOMAINS",
+    "CLOUDFLARE_ACCESS_OUTER_RING_AUTO_JOIN",
+    "EMAIL_PASSWORD_SIGN_IN",
+    // "false" keeps the hosted gateway's sign-up invite-only.
+    "HOSTED_OPEN_SIGNUP",
+    // Release deployers and the hosted third-party domain. The hosted launch
+    // gate, THIRD_PARTY_DEPLOYS, is never set from here: it is opened by
+    // hand once the launch checks pass (docs/runbooks/hosted-install.md).
+    "CF_DEPLOY_TOKEN",
+    // Self-hosted browser installs are on by default; "off" opts out.
+    "BROWSER_APP_INSTALLS",
+    "DISPATCH_NAMESPACE",
+    "THIRD_PARTY_DOMAIN",
+    // "true" lets event webhooks target http: and private hosts (self-host only).
+    "EVENTS_ALLOW_PRIVATE_TARGETS",
+];
+/**
+ * The Gateway's optional settings `everyapp secret set` changes: every
+ * setting a catalog provider reads, then the Gateway's own.
+ */
+export const SETTABLE_GATEWAY_SETTINGS = [
+    ...PROVIDER_GATEWAY_SETTINGS,
+    ...GATEWAY_OWN_SETTINGS,
+];
+const SETTABLE = new Set(SETTABLE_GATEWAY_SETTINGS);
+/**
+ * The credential names of remote MCP apps (`everyapp mcp add <url>`,
+ * ./remoteMcp.ts): `<ID>_MCP_TOKEN` by default, any name ending in
+ * `_MCP_TOKEN` by choice. A family rather than a list, so the names a
+ * registry row declares at run time route to the Gateway like the fixed
+ * names (`everyapp secret set` reads no registry to decide), an app's own
+ * secret can never take one (the manifest validator refuses the family),
+ * and a remote server can never be given a fixed provider key.
+ */
+export const REMOTE_MCP_SECRET_PATTERN = /^[A-Z][A-Z0-9_]*_MCP_TOKEN$/;
+/** Whether `name` is a remote MCP app's credential name (`TREG_MCP_TOKEN`). */
+export function isRemoteMcpSecretName(name) {
+    return REMOTE_MCP_SECRET_PATTERN.test(name);
+}
+/**
+ * Whether `everyapp secret set <name>` changes the Gateway: one of the
+ * fixed settings, or a remote MCP app's credential name.
+ */
+export function isSettableGatewaySetting(name) {
+    return SETTABLE.has(name) || isRemoteMcpSecretName(name);
+}
+/**
+ * Settable Gateway settings whose value is a plain word, address, list
+ * or switch rather than a credential: a sender, a provider choice, a
+ * URL, an audience, a flag. `everyapp secret set` may show these as they
+ * are typed and check their shape; anything else is a credential and
+ * stays hidden.
+ */
+export const PLAIN_GATEWAY_SETTINGS = [
+    "EMAIL_FROM",
+    "EMAIL_FROM_NAME",
+    "EMAIL_PROVIDER",
+    "EMAIL_PASSWORD_SIGN_IN",
+    "MASTODON_URL",
+    "AI_PROXY_EXTRA_ROUTES",
+    "MCP_OAUTH_ENABLED",
+    "MCP_DCR_ENABLED",
+    "MCP_ALLOWED_ORIGINS",
+    "MCP_AUDIT_RETENTION_DAYS",
+    "CLOUDFLARE_ACCESS_OIDC_ISSUER",
+    "CLOUDFLARE_ACCESS_OIDC_CLIENT_ID",
+    "CLOUDFLARE_ACCESS_OIDC_LABEL",
+    "CLOUDFLARE_ACCESS_TEAM_DOMAIN",
+    "CLOUDFLARE_ACCESS_AUD",
+    "CLOUDFLARE_ACCESS_APPS_AUD",
+    "CLOUDFLARE_ACCESS_AUTO_JOIN_DOMAINS",
+    "CLOUDFLARE_ACCESS_OUTER_RING_AUTO_JOIN",
+    "HOSTED_OPEN_SIGNUP",
+    "BROWSER_APP_INSTALLS",
+    "DISPATCH_NAMESPACE",
+    "THIRD_PARTY_DOMAIN",
+    "EVENTS_ALLOW_PRIVATE_TARGETS",
+];
+const PLAIN = new Set(PLAIN_GATEWAY_SETTINGS);
+/** Whether a settable Gateway setting's value is a plain value, not a credential. */
+export function isPlainGatewaySetting(name) {
+    return PLAIN.has(name);
+}
+/**
+ * Settable Gateway settings only the hosted gateway reads: a self-hosted
+ * install never needs them, so `secret list` leaves them out there.
+ */
+export const HOSTED_ONLY_GATEWAY_SETTINGS = [
+    "HOSTED_OPEN_SIGNUP",
+    "DISPATCH_NAMESPACE",
+    "THIRD_PARTY_DOMAIN",
+];
+const HOSTED_ONLY = new Set(HOSTED_ONLY_GATEWAY_SETTINGS);
+export function isHostedOnlyGatewaySetting(name) {
+    return HOSTED_ONLY.has(name);
+}
+/** Gateway settings for local testing only, set in the gateway's `.dev.vars`, never deployed. */
+export const DEV_ONLY_GATEWAY_SETTINGS = [
+    "MCP_ACCESS_TOKEN_TTL",
+    // "true" sends the DataForSEO provider app's calls to the free sandbox.
+    "DATAFORSEO_SANDBOX",
+];
+export function isDevOnlyGatewaySetting(name) {
+    return DEV_ONLY_GATEWAY_SETTINGS.includes(name);
+}
+/**
+ * Names an app's own secret can't take: the deploy sets GATEWAY_URL on
+ * every Worker and builds in the identity settings, the gateway binding
+ * and the platform's own namespaces. Checked without regard to case. The
+ * SDK's `everyAppWorker()` keeps the same rule as a regex (its config
+ * module can't import this one); a test keeps them in step.
+ */
+const RESERVED_APP_SECRET_NAMES = new Set([
+    "GATEWAY_URL",
+    "CF_VERSION_METADATA",
+]);
+const RESERVED_APP_SECRET_PREFIXES = [
+    "EVERYAPP_",
+    "EVERY_APP_",
+    "APP__",
+];
+/** What the reserved names are, for messages. */
+export const RESERVED_APP_SECRET_NAMES_TEXT = "GATEWAY_URL, CF_VERSION_METADATA and the EVERYAPP_*, EVERY_APP_* and APP__* names";
+export function isReservedAppSecretName(name) {
+    const upper = name.toUpperCase();
+    return (RESERVED_APP_SECRET_NAMES.has(upper) ||
+        RESERVED_APP_SECRET_PREFIXES.some((prefix) => upper.startsWith(prefix)));
+}
+/**
+ * The AI provider or capability a Gateway setting belongs to: what to list
+ * in a manifest instead of holding the key as the app's own.
+ */
+export function gatewaySettingOwner(name) {
+    for (const id of CAPABILITY_IDS) {
+        const capability = CAPABILITIES[id];
+        if (capabilitySettings(capability).includes(name)) {
+            return { kind: capability.mode === "ai" ? "provider" : "capability", id };
+        }
+    }
+    return null;
+}

package/dist/internal/identity.d.ts

@@ -0,0 +1,88 @@
+import { APP_ID_ENV, DEV_ENV, DEV_ISSUER, IDENTITY_ALG, IDENTITY_DEV_KEY_ID, IDENTITY_HEADER, IDENTITY_KEY_ID, ISSUER_ENV, PUBLIC_HEADER, PUBLIC_KEYS_ENV, PUBLIC_MARKER_SUB, type EveryAppUser, type IdentityChannel, type SystemClaims, type SystemTokenPurpose } from "./protocol.js";
+export { APP_ID_ENV, DEV_ENV, DEV_ISSUER, IDENTITY_ALG, IDENTITY_DEV_KEY_ID, IDENTITY_HEADER, IDENTITY_KEY_ID, ISSUER_ENV, PUBLIC_HEADER, PUBLIC_KEYS_ENV, PUBLIC_MARKER_SUB, type EveryAppUser, type IdentityChannel, };
+export declare class IdentityError extends Error {
+    readonly status = 401;
+    constructor(message: string);
+}
+export declare class ConfigurationError extends Error {
+    readonly status = 500;
+    constructor(message: string);
+}
+/**
+ * Parse the public key set from an env var value. Accepts a JSON array of PEM
+ * strings, or a single PEM string. Returns at least one key or throws.
+ */
+export declare function parsePublicKeys(envValue: string | undefined | null): string[];
+export interface VerifyOptions {
+    /** SPKI PEM public keys (current + next). */
+    publicKeys: string[];
+    /** Expected `aud` — this app's id. */
+    audience: string;
+    /** Expected issuer (the gateway URL). Required for user identities. */
+    issuer?: string;
+    /**
+     * Accept the dev identity kid ({@link IDENTITY_DEV_KEY_ID}). Set ONLY in
+     * local dev (driven by the {@link DEV_ENV} worker env var). Never true in
+     * production. Requires `issuer` to be {@link DEV_ISSUER}.
+     */
+    allowDevIdentities?: boolean;
+    /** Override for tests. */
+    now?: number;
+}
+/**
+ * Verify an identity JWT fail-closed. Throws {@link IdentityError} on any
+ * problem (bad alg/kid, `none`, wrong key, expired, wrong audience, missing
+ * claims).
+ */
+export declare function verifyIdentityJwt(token: string, options: VerifyOptions): Promise<EveryAppUser>;
+/**
+ * Verify the gateway's system token (the value of `x-everyapp-system`)
+ * fail-closed, for exactly one purpose. A user identity or public marker is
+ * never a system token, and a system token is never an identity.
+ */
+export declare function verifySystemJwt(token: string, options: VerifyOptions & {
+    purpose: SystemTokenPurpose;
+}): Promise<SystemClaims>;
+/**
+ * Verify a public-route marker (the value of `x-everyapp-public`). The marker
+ * is a gateway-signed, app-scoped JWT with `pub: true` and `typ: "public"` —
+ * a bare header is NEVER a trust source, so a re-exposed app worker cannot be
+ * flipped into public mode by anyone who can type a header. Throws on any
+ * problem.
+ */
+export declare function verifyPublicMarkerJwt(token: string, options: VerifyOptions): Promise<void>;
+export interface IdentityResult {
+    /** The verified user, or null for a declared public route. */
+    user: EveryAppUser | null;
+    /** True when the gateway marked this request as a public route. */
+    isPublic: boolean;
+}
+export interface RequestIdentityOptions {
+    audience: string;
+    /** Provide keys directly, or let {@link getIdentityFromRequest} read env. */
+    publicKeys?: string[];
+    /** Env bag to read {@link PUBLIC_KEYS_ENV} / {@link DEV_ENV} from. */
+    env?: Record<string, unknown>;
+    keysEnvVar?: string;
+    issuer?: string;
+    /** Force dev-kid acceptance. Defaults to reading {@link DEV_ENV} from env. */
+    allowDevIdentities?: boolean;
+    now?: number;
+}
+/**
+ * The verification options for a request: keys from options or env, the
+ * expected issuer, and the dev-kid opt-in. Throws {@link ConfigurationError}
+ * when no key set is configured, or when the dev opt-in meets an issuer other
+ * than {@link DEV_ISSUER}.
+ */
+export declare function resolveVerifyOptions(options: RequestIdentityOptions): VerifyOptions;
+/**
+ * Resolve identity for an incoming proxied request. Public routes carry a
+ * gateway-SIGNED marker in `x-everyapp-public` and resolve to
+ * `{ user: null, isPublic: true }` only after the marker verifies. Everything
+ * else requires a valid identity JWT. Throws {@link IdentityError} on any
+ * problem — including a bare/forged public header — so a re-exposed worker
+ * fails closed.
+ */
+export declare function getIdentityFromRequest(request: Request, options: RequestIdentityOptions): Promise<IdentityResult>;
+//# sourceMappingURL=identity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/internal/identity.ts"],"names":[],"mappings":"AAgBA,OAAO,EACL,UAAU,EACV,OAAO,EACP,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,UAAU,EACV,aAAa,EACb,eAAe,EACf,iBAAiB,EAKjB,KAAK,YAAY,EACjB,KAAK,eAAe,EAEpB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,UAAU,EACV,OAAO,EACP,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,UAAU,EACV,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,CAAC;AAEF,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,MAAM,OAAO;gBACV,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,MAAM,OAAO;gBACV,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,EAAE,CA8B7E;AAYD,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,0BAA0B;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAeD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,YAAY,CAAC,CAUvB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,GAAG;IAAE,OAAO,EAAE,kBAAkB,CAAA;CAAE,GACvD,OAAO,CAAC,YAAY,CAAC,CAUvB;AAoED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,sBAAsB,GAC9B,aAAa,CAwBf;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,cAAc,CAAC,CAiBzB"}

package/dist/internal/identity.js

@@ -0,0 +1,231 @@
+/**
+ * Every App identity JWT verification (the app side of the trust boundary).
+ *
+ * The gateway injects a short-lived RS256 JWT as `x-everyapp-identity`. This
+ * module verifies it **fail-closed**: the algorithm and key id are pinned,
+ * `none` is rejected, the audience must equal this app, and the verification
+ * key set arrives from an env var (current + next public keys) — never a
+ * runtime JWKS fetch. A bare header is never a trust source; only a token that
+ * survives verification produces a user.
+ */
+import { importSPKI, jwtVerify, decodeProtectedHeader, } from "jose";
+import { APP_ID_ENV, DEV_ENV, DEV_ISSUER, IDENTITY_ALG, IDENTITY_DEV_KEY_ID, IDENTITY_HEADER, IDENTITY_KEY_ID, ISSUER_ENV, PUBLIC_HEADER, PUBLIC_KEYS_ENV, PUBLIC_MARKER_SUB, assertPublicMarkerClaims, assertSystemClaims, identityClaimsToEveryAppUser, ProtocolClaimsError, } from "./protocol.js";
+export { APP_ID_ENV, DEV_ENV, DEV_ISSUER, IDENTITY_ALG, IDENTITY_DEV_KEY_ID, IDENTITY_HEADER, IDENTITY_KEY_ID, ISSUER_ENV, PUBLIC_HEADER, PUBLIC_KEYS_ENV, PUBLIC_MARKER_SUB, };
+export class IdentityError extends Error {
+    status = 401;
+    constructor(message) {
+        super(message);
+        this.name = "IdentityError";
+    }
+}
+export class ConfigurationError extends Error {
+    status = 500;
+    constructor(message) {
+        super(message);
+        this.name = "ConfigurationError";
+    }
+}
+/**
+ * Parse the public key set from an env var value. Accepts a JSON array of PEM
+ * strings, or a single PEM string. Returns at least one key or throws.
+ */
+export function parsePublicKeys(envValue) {
+    if (!envValue || envValue.trim().length === 0) {
+        throw new ConfigurationError(`${PUBLIC_KEYS_ENV} is not set — the gateway must inject the identity public key set.`);
+    }
+    const trimmed = envValue.trim();
+    let keys;
+    if (trimmed.startsWith("[")) {
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (error) {
+            throw new ConfigurationError(`${PUBLIC_KEYS_ENV} must be a JSON array of PEM strings: ${error.message}`);
+        }
+        if (!Array.isArray(parsed) || parsed.some((k) => typeof k !== "string")) {
+            throw new ConfigurationError(`${PUBLIC_KEYS_ENV} must be a JSON array of PEM strings.`);
+        }
+        keys = parsed.map((k) => k.replace(/\\n/g, "\n"));
+    }
+    else {
+        keys = [trimmed.replace(/\\n/g, "\n")];
+    }
+    if (keys.length === 0) {
+        throw new ConfigurationError(`${PUBLIC_KEYS_ENV} contained no keys.`);
+    }
+    return keys;
+}
+const keyCache = new Map();
+function importKey(pem) {
+    let cached = keyCache.get(pem);
+    if (!cached) {
+        cached = importSPKI(pem, IDENTITY_ALG);
+        keyCache.set(pem, cached);
+    }
+    return cached;
+}
+/**
+ * The dev keypair is public (`@every-app/sdk/dev`), so the dev opt-in holds
+ * only for the dev issuer: a dev-kid token that names a real gateway as its
+ * issuer never verifies, whatever the env says.
+ */
+function assertDevIssuer(options) {
+    if (options.allowDevIdentities && options.issuer !== DEV_ISSUER) {
+        throw new ConfigurationError(`Dev identities are accepted only from the dev issuer ${DEV_ISSUER}, not ${options.issuer ? `"${options.issuer}"` : "an unset issuer"}. ${DEV_ENV} is for \`everyapp dev\` alone.`);
+    }
+}
+/**
+ * Verify an identity JWT fail-closed. Throws {@link IdentityError} on any
+ * problem (bad alg/kid, `none`, wrong key, expired, wrong audience, missing
+ * claims).
+ */
+export async function verifyIdentityJwt(token, options) {
+    const payload = await verifyPinnedJwt(token, options, "user");
+    try {
+        return identityClaimsToEveryAppUser(payload);
+    }
+    catch (error) {
+        if (error instanceof ProtocolClaimsError) {
+            throw new IdentityError(error.message);
+        }
+        throw error;
+    }
+}
+/**
+ * Verify the gateway's system token (the value of `x-everyapp-system`)
+ * fail-closed, for exactly one purpose. A user identity or public marker is
+ * never a system token, and a system token is never an identity.
+ */
+export async function verifySystemJwt(token, options) {
+    const payload = await verifyPinnedJwt(token, options, "system");
+    try {
+        return assertSystemClaims(payload, options.purpose);
+    }
+    catch (error) {
+        if (error instanceof ProtocolClaimsError) {
+            throw new IdentityError(error.message);
+        }
+        throw error;
+    }
+}
+/**
+ * The shared fail-closed verification core: pinned alg/kid, `none` rejected,
+ * `aud` checked, multi-key (current + next). Returns the verified payload.
+ */
+async function verifyPinnedJwt(token, options, expectedTyp) {
+    assertDevIssuer(options);
+    if (!token)
+        throw new IdentityError("no identity token");
+    // Pin the header BEFORE attempting any signature work. This is what defeats
+    // `alg: none` and algorithm-confusion (e.g. an HS256 token forged with the
+    // public key as the HMAC secret).
+    let header;
+    try {
+        header = decodeProtectedHeader(token);
+    }
+    catch {
+        throw new IdentityError("malformed identity token");
+    }
+    if (header.alg !== IDENTITY_ALG) {
+        throw new IdentityError(`unexpected alg "${header.alg}" (expected ${IDENTITY_ALG})`);
+    }
+    const allowedKids = options.allowDevIdentities
+        ? [IDENTITY_KEY_ID, IDENTITY_DEV_KEY_ID]
+        : [IDENTITY_KEY_ID];
+    if (!header.kid || !allowedKids.includes(header.kid)) {
+        throw new IdentityError(`unexpected kid "${header.kid}"`);
+    }
+    if (expectedTyp !== "public" && !options.issuer) {
+        throw new IdentityError(`${ISSUER_ENV} not configured — deploy with the Every App CLI or provide an explicit issuer.`);
+    }
+    const verifyOpts = {
+        algorithms: [IDENTITY_ALG],
+        audience: options.audience,
+        requiredClaims: expectedTyp === "system" ? ["exp", "iat"] : ["exp"],
+        ...(options.issuer ? { issuer: options.issuer } : {}),
+        ...(options.now ? { currentDate: new Date(options.now) } : {}),
+    };
+    let lastErr;
+    for (const pem of options.publicKeys) {
+        try {
+            const key = await importKey(pem);
+            const { payload } = await jwtVerify(token, key, verifyOpts);
+            if (payload.typ !== expectedTyp) {
+                throw new IdentityError(`unexpected token typ "${payload.typ}" (expected ${expectedTyp})`);
+            }
+            return payload;
+        }
+        catch (err) {
+            lastErr = err;
+        }
+    }
+    throw new IdentityError(`identity verification failed: ${lastErr?.message ?? "no matching key"}`);
+}
+/**
+ * Verify a public-route marker (the value of `x-everyapp-public`). The marker
+ * is a gateway-signed, app-scoped JWT with `pub: true` and `typ: "public"` —
+ * a bare header is NEVER a trust source, so a re-exposed app worker cannot be
+ * flipped into public mode by anyone who can type a header. Throws on any
+ * problem.
+ */
+export async function verifyPublicMarkerJwt(token, options) {
+    const payload = await verifyPinnedJwt(token, options, "public");
+    try {
+        assertPublicMarkerClaims(payload);
+    }
+    catch (error) {
+        if (error instanceof ProtocolClaimsError) {
+            throw new IdentityError(error.message);
+        }
+        throw error;
+    }
+}
+/**
+ * The verification options for a request: keys from options or env, the
+ * expected issuer, and the dev-kid opt-in. Throws {@link ConfigurationError}
+ * when no key set is configured, or when the dev opt-in meets an issuer other
+ * than {@link DEV_ISSUER}.
+ */
+export function resolveVerifyOptions(options) {
+    const publicKeys = options.publicKeys ??
+        parsePublicKeys(options.env?.[options.keysEnvVar ?? PUBLIC_KEYS_ENV] ?? null);
+    // Dev identities are accepted only when the worker env opts in
+    // (everyAppWorker() sets EVERYAPP_DEV in development). A deploy never does.
+    const devEnv = options.env?.[DEV_ENV];
+    const allowDevIdentities = options.allowDevIdentities ??
+        (typeof devEnv === "string" &&
+            (devEnv === "1" || devEnv.toLowerCase() === "true"));
+    const resolved = {
+        publicKeys,
+        audience: options.audience,
+        issuer: options.issuer ??
+            (options.env?.[ISSUER_ENV] || undefined),
+        allowDevIdentities,
+        now: options.now,
+    };
+    assertDevIssuer(resolved);
+    return resolved;
+}
+/**
+ * Resolve identity for an incoming proxied request. Public routes carry a
+ * gateway-SIGNED marker in `x-everyapp-public` and resolve to
+ * `{ user: null, isPublic: true }` only after the marker verifies. Everything
+ * else requires a valid identity JWT. Throws {@link IdentityError} on any
+ * problem — including a bare/forged public header — so a re-exposed worker
+ * fails closed.
+ */
+export async function getIdentityFromRequest(request, options) {
+    const verifyOptions = resolveVerifyOptions(options);
+    const publicMarker = request.headers.get(PUBLIC_HEADER);
+    if (publicMarker) {
+        await verifyPublicMarkerJwt(publicMarker, verifyOptions);
+        return { user: null, isPublic: true };
+    }
+    const token = request.headers.get(IDENTITY_HEADER);
+    if (!token) {
+        throw new IdentityError("request reached the app without an identity token (not proxied through the gateway?)");
+    }
+    const user = await verifyIdentityJwt(token, verifyOptions);
+    return { user, isPublic: false };
+}

package/dist/internal/index.d.ts

@@ -0,0 +1,19 @@
+export * from "./protocol.js";
+export * from "./tools.js";
+export * from "./capabilities.js";
+export * from "./aiProviders.js";
+export * from "./gatewaySettings.js";
+export * from "./appSettings.js";
+export * from "./email.js";
+export * from "./members.js";
+export * from "./organizationName.js";
+export * from "./oauthClient.js";
+export * from "./oauthScopes.js";
+export * from "./providerApps.js";
+export * from "./events.js";
+export * from "./providerSpec.js";
+export * from "./providerRegistry.js";
+export * from "./remoteMcp.js";
+export * from "./devProviders.js";
+export { ConfigurationError, IdentityError, getIdentityFromRequest, parsePublicKeys, resolveVerifyOptions, verifyIdentityJwt, verifyPublicMarkerJwt, verifySystemJwt, type IdentityResult, type RequestIdentityOptions, type VerifyOptions, } from "./identity.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/internal/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC"}

package/dist/internal/index.js

@@ -0,0 +1,18 @@
+export * from "./protocol.js";
+export * from "./tools.js";
+export * from "./capabilities.js";
+export * from "./aiProviders.js";
+export * from "./gatewaySettings.js";
+export * from "./appSettings.js";
+export * from "./email.js";
+export * from "./members.js";
+export * from "./organizationName.js";
+export * from "./oauthClient.js";
+export * from "./oauthScopes.js";
+export * from "./providerApps.js";
+export * from "./events.js";
+export * from "./providerSpec.js";
+export * from "./providerRegistry.js";
+export * from "./remoteMcp.js";
+export * from "./devProviders.js";
+export { ConfigurationError, IdentityError, getIdentityFromRequest, parsePublicKeys, resolveVerifyOptions, verifyIdentityJwt, verifyPublicMarkerJwt, verifySystemJwt, } from "./identity.js";

package/dist/internal/members.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The `members` capability's wire contract (docs/capabilities.md "Gateway
+ * services"): what `GET /api/integrations/members/list` answers. The
+ * gateway builds it, the SDK's `listMembers()` returns it, and its local-dev
+ * fallback answers in the same shape. Types only.
+ */
+/** A member's role in the organization. */
+export type OrganizationMemberRole = "owner" | "admin" | "member";
+/**
+ * One member of the organization who can open the app: not deactivated,
+ * and, for an organization's own app, granted it.
+ */
+export interface OrganizationMember {
+    /** The user id, the identity's `sub` (`getEveryAppUser().id`). */
+    id: string;
+    email: string;
+    /** The display name; empty when the person set none. */
+    name: string;
+    role: OrganizationMemberRole;
+}
+/** What a list answers. */
+export interface ListMembersResult {
+    members: OrganizationMember[];
+}
+/** `GET /api/integrations/members`: whether the app may list members. */
+export interface MembersCapabilityStatus {
+    capability: "members";
+    /** The app's manifest lists `members`. */
+    requested: boolean;
+    /** Always true: the gateway needs no setting to list its own members. */
+    configured: true;
+    /** Lists would go through. */
+    ready: boolean;
+}
+//# sourceMappingURL=members.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"members.d.ts","sourceRoot":"","sources":["../../src/internal/members.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,2CAA2C;AAC3C,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAElE;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,sBAAsB,CAAC;CAC9B;AAED,2BAA2B;AAC3B,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;CAC/B;AAED,yEAAyE;AACzE,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,SAAS,CAAC;IACtB,0CAA0C;IAC1C,SAAS,EAAE,OAAO,CAAC;IACnB,yEAAyE;IACzE,UAAU,EAAE,IAAI,CAAC;IACjB,8BAA8B;IAC9B,KAAK,EAAE,OAAO,CAAC;CAChB"}

package/dist/internal/members.js

@@ -0,0 +1,7 @@
+/**
+ * The `members` capability's wire contract (docs/capabilities.md "Gateway
+ * services"): what `GET /api/integrations/members/list` answers. The
+ * gateway builds it, the SDK's `listMembers()` returns it, and its local-dev
+ * fallback answers in the same shape. Types only.
+ */
+export {};