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

package/dist/internal/gatewaySettings.js

@@ -0,0 +1,217 @@
+/**
+ * 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";
+import { PLAIN_SIGN_IN_SETTINGS, SIGN_IN_GATEWAY_SETTINGS, } from "./signInProviders.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, the Gateway's own, then the sign-in
+ * providers' (`<ID>_SIGNIN_<FIELD>`, ./signInProviders.ts).
+ */
+export const SETTABLE_GATEWAY_SETTINGS = [
+    ...PROVIDER_GATEWAY_SETTINGS,
+    ...GATEWAY_OWN_SETTINGS,
+    ...SIGN_IN_GATEWAY_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,
+    // The sign-in providers' ids, issuer, label and tenant; their client
+    // secrets are credentials.
+    ...PLAIN_SIGN_IN_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

@@ -1,5 +1,5 @@
-import { APP_ID_ENV, DEV_ENV, 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 } from "./protocol.js";
-export { APP_ID_ENV, DEV_ENV, 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, };
+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);
@@ -23,7 +23,7 @@ export interface VerifyOptions {
     /**
      * 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.
+     * production. Requires `issuer` to be {@link DEV_ISSUER}.
      */
     allowDevIdentities?: boolean;
     /** Override for tests. */
@@ -35,6 +35,14 @@ export interface VerifyOptions {
  * 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"` —
@@ -61,6 +69,13 @@ export interface RequestIdentityOptions {
     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

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

@@ -1 +1 @@
-{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/internal/identity.ts"],"names":[],"mappings":"AAgBA,OAAO,EACL,UAAU,EACV,OAAO,EACP,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,UAAU,EACV,aAAa,EACb,eAAe,EACf,iBAAiB,EAIjB,KAAK,YAAY,EACjB,KAAK,eAAe,EAErB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,UAAU,EACV,OAAO,EACP,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;AAmED;;;;;;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;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,cAAc,CAAC,CAqCzB"}
+{"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

@@ -9,8 +9,8 @@
  * survives verification produces a user.
  */
 import { importSPKI, jwtVerify, decodeProtectedHeader, } from "jose";
-import { APP_ID_ENV, DEV_ENV, IDENTITY_ALG, IDENTITY_DEV_KEY_ID, IDENTITY_HEADER, IDENTITY_KEY_ID, ISSUER_ENV, PUBLIC_HEADER, PUBLIC_KEYS_ENV, PUBLIC_MARKER_SUB, assertPublicMarkerClaims, identityClaimsToEveryAppUser, ProtocolClaimsError, } from "./protocol.js";
-export { APP_ID_ENV, DEV_ENV, IDENTITY_ALG, IDENTITY_DEV_KEY_ID, IDENTITY_HEADER, IDENTITY_KEY_ID, ISSUER_ENV, PUBLIC_HEADER, PUBLIC_KEYS_ENV, PUBLIC_MARKER_SUB, };
+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) {
@@ -65,6 +65,16 @@ function importKey(pem) {
     }
     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
@@ -82,11 +92,29 @@ export async function verifyIdentityJwt(token, options) {
         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
@@ -108,13 +136,13 @@ async function verifyPinnedJwt(token, options, expectedTyp) {
     if (!header.kid || !allowedKids.includes(header.kid)) {
         throw new IdentityError(`unexpected kid "${header.kid}"`);
     }
-    if (expectedTyp === "user" && !options.issuer) {
+    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: ["exp"],
+        requiredClaims: expectedTyp === "system" ? ["exp", "iat"] : ["exp"],
         ...(options.issuer ? { issuer: options.issuer } : {}),
         ...(options.now ? { currentDate: new Date(options.now) } : {}),
     };
@@ -154,23 +182,21 @@ export async function verifyPublicMarkerJwt(token, options) {
     }
 }
 /**
- * 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.
+ * 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 async function getIdentityFromRequest(request, options) {
+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 (everyapp dev
-    // sets EVERYAPP_DEV in .dev.vars). Production never sets it.
+    // 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 verifyOptions = {
+    const resolved = {
         publicKeys,
         audience: options.audience,
         issuer: options.issuer ??
@@ -178,6 +204,19 @@ export async function getIdentityFromRequest(request, options) {
         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);

package/dist/internal/index.d.ts

@@ -1,3 +1,20 @@
 export * from "./protocol.js";
-export { ConfigurationError, IdentityError, getIdentityFromRequest, parsePublicKeys, verifyIdentityJwt, verifyPublicMarkerJwt, type IdentityResult, type RequestIdentityOptions, type VerifyOptions, } from "./identity.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 "./signInProviders.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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/internal/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC"}
+{"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,sBAAsB,CAAC;AACrC,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

@@ -1,2 +1,19 @@
 export * from "./protocol.js";
-export { ConfigurationError, IdentityError, getIdentityFromRequest, parsePublicKeys, verifyIdentityJwt, verifyPublicMarkerJwt, } from "./identity.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 "./signInProviders.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 {};

package/dist/internal/oauthClient.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The `oauth_client` capability's wire rules (docs/capabilities.md "OAuth
+ * clients"), shared by the gateway, which puts the operator's client on an
+ * app's token request, and the SDK's local-dev fallback, which puts the
+ * developer's own on it the same way.
+ */
+import { type CapabilitySettings, type OAuthClientCapability, type OAuthTokenEndpoint } from "./capabilities.js";
+/** The largest token request body the gateway reads: real ones are a few hundred bytes. */
+export declare const OAUTH_TOKEN_BODY_LIMIT: number;
+/** An OAuth client as the gateway (or `.dev.vars`) holds it. */
+export interface OAuthClientCredentials {
+    clientId: string;
+    /** Absent for a public client. */
+    clientSecret?: string;
+}
+/**
+ * The client `settings` hold for `capability`, or null until every setting
+ * it needs is set: the id, the secret (unless it is a public client), and a
+ * `hostSetting` that is an https origin when it is set at all.
+ */
+export declare function oauthClientCredentials(capability: OAuthClientCapability, settings: CapabilitySettings): OAuthClientCredentials | null;
+/** A token request: where it goes, its headers, its (buffered) body. */
+export interface TokenRequest {
+    url: URL;
+    headers: Headers;
+    body: string | null;
+}
+export type InjectedTokenRequest = ({
+    ok: true;
+} & TokenRequest) | {
+    ok: false;
+    problem: string;
+};
+/**
+ * `request` with `client` put where `rule` says (the form body, HTTP Basic,
+ * the query string or the JSON body), and every client credential the app
+ * sent removed wherever it was: the `Authorization` header, and
+ * `client_id`/`client_secret` (or the rule's names for them, in any case) in
+ * the query string and the body. Bodies are re-serialised from their parsed
+ * values, so a crafted body can't carry a second secret past the parser.
+ * Token requests are form-encoded or JSON; anything else is refused.
+ */
+export declare function injectClientCredentials(request: TokenRequest, rule: OAuthTokenEndpoint, client: OAuthClientCredentials): InjectedTokenRequest;
+/**
+ * The grants the gateway completes: each ends in a user's own tokens. The
+ * client-credentials grant, and anything else a network serves on the same
+ * endpoint, would mint a token for the gateway's own application instead,
+ * which on Meta, Discord, Twitch or Kick manages the application's
+ * settings, its webhooks and every tenant's tokens.
+ */
+export declare const USER_BOUND_GRANT_TYPES: ReadonlySet<string>;
+/**
+ * A token request's `grant_type` as the app sent it, from its body or query
+ * string, or null when it names none (Meta's code exchange). Never the
+ * request's other fields.
+ */
+export declare function requestedGrantType(request: TokenRequest): string | null;
+/**
+ * A token request's `grant_type` for logs: one of the known grant types,
+ * `other`, or null when it names none.
+ */
+export declare function tokenGrantType(request: TokenRequest): string | null;
+//# sourceMappingURL=oauthClient.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oauthClient.d.ts","sourceRoot":"","sources":["../../src/internal/oauthClient.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAY,CAAC;AAEhD,gEAAgE;AAChE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,qBAAqB,EACjC,QAAQ,EAAE,kBAAkB,GAC3B,sBAAsB,GAAG,IAAI,CAW/B;AAMD,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,GAAG,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,MAAM,oBAAoB,GAC5B,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,YAAY,CAAC,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAKnC;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,kBAAkB,EACxB,MAAM,EAAE,sBAAsB,GAC7B,oBAAoB,CAyFtB;AAaD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAOrD,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAUvE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAInE"}