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

package/dist/internal/oauthSpec.js

@@ -0,0 +1,520 @@
+const SEPARATORS = ["space", "comma"];
+const INJECTIONS = ["form", "basic"];
+const HEADER_NAME = /^[A-Za-z0-9-]{1,64}$/;
+/** Headers the Gateway sets on the token request itself, or never sends. */
+const RESERVED_TOKEN_HEADERS = new Set([
+    "authorization",
+    "content-type",
+    "content-length",
+    "host",
+    "cookie",
+]);
+/**
+ * Authorize parameters the Gateway sets itself, and
+ * `include_granted_scopes`, which would widen a token to every scope the
+ * person ever granted the client (the mint check would refuse it anyway).
+ */
+const RESERVED_AUTHORIZE_PARAMS = [
+    "client_id",
+    "redirect_uri",
+    "response_type",
+    "scope",
+    "state",
+    "code_challenge",
+    "code_challenge_method",
+    "include_granted_scopes",
+];
+const PARAM_NAME = /^[A-Za-z0-9_.-]{1,64}$/;
+/** A dot path into a JSON answer, at most four segments. */
+const DOT_PATH = /^[A-Za-z_][A-Za-z0-9_]{0,63}(?:\.[A-Za-z_][A-Za-z0-9_]{0,63}){0,3}$/;
+const UNPRINTABLE = /[\p{Cc}\p{Cf}]/u;
+const MAX_SCOPES = 40;
+const MAX_PARAMS = 10;
+/** The fields of `auth` when its kind is `oauth2-user`. */
+export const OAUTH_AUTH_FIELDS = [
+    "kind",
+    "authorizeUrl",
+    "tokenUrl",
+    "revokeUrl",
+    "revokeMethod",
+    "clientId",
+    "clientSecret",
+    "inject",
+    "pkce",
+    "scopeSeparator",
+    "scopePrefix",
+    "authorizeParams",
+    "tokenHeaders",
+    "identity",
+    "tolerated",
+];
+/**
+ * Fields an `oauth2-user` spec had before scopes moved to each app's
+ * `everyapp.config.ts`, each with what to write instead: refused with
+ * that message rather than "unknown field".
+ */
+export const REMOVED_OAUTH_FIELDS = {
+    scopeSets: "scope sets are gone: each app lists the provider's own scopes in its everyapp.config.ts. Remove scopeSets.",
+    alwaysRequested: "alwaysRequested is gone: put scopes every connect needs (a refresh token's, the identity URL's) in auth.identity.scopes.",
+    tolerated: "tolerated moved into auth: auth.tolerated lists the scopes a token may carry beyond what was asked.",
+    access: "access is gone for an OAuth provider: the scopes an app lists are the grant, for every method.",
+    readMethods: "readMethods is gone for an OAuth provider: the scopes an app lists are the grant, for every method.",
+    writeMethods: "writeMethods is gone for an OAuth provider: the scopes an app lists are the grant, for every method.",
+};
+/** `auth` fields renamed, each with its new name. */
+const RENAMED_AUTH_FIELDS = {
+    scopeDialect: "renamed auth.scopeSeparator: space or comma (a provider's prefix goes in auth.scopePrefix)",
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function printable(value, path, problems, max) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value.length === 0 || value.length > max) {
+        problems.push({
+            path,
+            message: `must be a string of 1 to ${max} characters`,
+        });
+        return undefined;
+    }
+    if (UNPRINTABLE.test(value)) {
+        problems.push({ path, message: "holds a control character" });
+        return undefined;
+    }
+    return value;
+}
+/**
+ * An https URL with a host a row may name (the caller runs the gateway's
+ * host rules on `host` afterwards). `{client_id}` may stand in a path
+ * (GitHub's revoke URL names the client there).
+ */
+function endpoint(value, path, problems, { query }) {
+    if (value === undefined)
+        return undefined;
+    const url = printable(value, path, problems, 500);
+    if (url === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        problems.push({ path, message: "must be an https URL" });
+        return undefined;
+    }
+    if (parsed.protocol !== "https:" ||
+        parsed.username ||
+        parsed.password ||
+        parsed.port ||
+        parsed.hash) {
+        problems.push({
+            path,
+            message: "must be an https URL with no port, credentials or fragment",
+        });
+        return undefined;
+    }
+    if (!query && parsed.search) {
+        problems.push({ path, message: "may not carry a query string" });
+        return undefined;
+    }
+    return { url, host: parsed.hostname.toLowerCase() };
+}
+function settingName(value, path, problems) {
+    if (typeof value !== "string" || !/^[A-Z][A-Z0-9_]{2,63}$/.test(value)) {
+        problems.push({
+            path,
+            message: "must name a Gateway setting: upper case letters, digits and underscores, a letter first, 3 to 64 characters (GITHUB_CLIENT_ID)",
+        });
+        return undefined;
+    }
+    return value;
+}
+function stringMap(value, path, problems, each) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value)) {
+        problems.push({ path, message: "must be an object of strings" });
+        return undefined;
+    }
+    const entries = Object.entries(value);
+    if (entries.length > MAX_PARAMS) {
+        problems.push({ path, message: `at most ${MAX_PARAMS} entries` });
+        return undefined;
+    }
+    const out = {};
+    for (const [name, raw] of entries) {
+        const at = `${path}.${name}`;
+        each(name, at);
+        const text = printable(raw, at, problems, 200);
+        if (text !== undefined)
+            out[name] = text;
+    }
+    return out;
+}
+/** A list of provider scope strings: each one scope, with no space or comma, each once. */
+export function scopeList(value, path, problems) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length > MAX_SCOPES) {
+        problems.push({
+            path,
+            message: `must be a list of at most ${MAX_SCOPES} scopes`,
+        });
+        return undefined;
+    }
+    const out = [];
+    value.forEach((item, index) => {
+        const scope = printable(item, `${path}.${index}`, problems, 200);
+        if (scope === undefined)
+            return;
+        if (/\s/.test(scope) || scope.includes(",")) {
+            problems.push({
+                path: `${path}.${index}`,
+                message: "one scope, with no space or comma",
+            });
+            return;
+        }
+        out.push(scope);
+    });
+    if (new Set(out).size !== out.length) {
+        problems.push({ path, message: "lists a scope twice" });
+    }
+    return out;
+}
+function identity(value, hosts, problems) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value)) {
+        problems.push({
+            path: "auth.identity",
+            message: "must be { url, label, id?, scopes? }",
+        });
+        return undefined;
+    }
+    for (const field of Object.keys(value)) {
+        if (!["url", "label", "id", "scopes"].includes(field)) {
+            problems.push({
+                path: `auth.identity.${field}`,
+                message: "unknown field",
+            });
+        }
+    }
+    const url = endpoint(value["url"], "auth.identity.url", problems, {
+        query: true,
+    });
+    if (value["url"] === undefined) {
+        problems.push({ path: "auth.identity.url", message: "required" });
+    }
+    else if (url && !hosts.includes(url.host)) {
+        problems.push({
+            path: "auth.identity.url",
+            message: "must be on one of hosts (the token is sent there)",
+        });
+    }
+    const label = printable(value["label"], "auth.identity.label", problems, 128);
+    if (label !== undefined && !DOT_PATH.test(label)) {
+        problems.push({
+            path: "auth.identity.label",
+            message: "must be a JSON field name, or a dotted path to a nested one",
+        });
+    }
+    if (value["label"] === undefined) {
+        problems.push({ path: "auth.identity.label", message: "required" });
+    }
+    const id = printable(value["id"], "auth.identity.id", problems, 128);
+    if (id !== undefined && !DOT_PATH.test(id)) {
+        problems.push({
+            path: "auth.identity.id",
+            message: "must be a JSON field name, or a dotted path to a nested one",
+        });
+    }
+    const scopes = scopeList(value["scopes"], "auth.identity.scopes", problems);
+    if (!url || label === undefined)
+        return undefined;
+    return {
+        identity: { url: url.url, label, ...(id === undefined ? {} : { id }) },
+        scopes: scopes ?? [],
+    };
+}
+/**
+ * Parse the OAuth half of a spec whose `auth.kind` is `oauth2-user`, with
+ * the common fields already parsed. Every problem is reported; on success
+ * the capability with its `flow`.
+ */
+export function parseOAuthUserSpec(input, common, problems) {
+    const auth = input["auth"];
+    for (const field of Object.keys(auth)) {
+        const renamed = RENAMED_AUTH_FIELDS[field];
+        if (renamed) {
+            problems.push({ path: `auth.${field}`, message: renamed });
+        }
+        else if (!OAUTH_AUTH_FIELDS.includes(field)) {
+            problems.push({
+                path: `auth.${field}`,
+                message: "not a field of auth.kind oauth2-user",
+            });
+        }
+    }
+    const authorize = endpoint(auth["authorizeUrl"], "auth.authorizeUrl", problems, { query: true });
+    if (auth["authorizeUrl"] === undefined) {
+        problems.push({ path: "auth.authorizeUrl", message: "required" });
+    }
+    const token = endpoint(auth["tokenUrl"], "auth.tokenUrl", problems, {
+        query: false,
+    });
+    if (auth["tokenUrl"] === undefined) {
+        problems.push({ path: "auth.tokenUrl", message: "required" });
+    }
+    const revoke = endpoint(auth["revokeUrl"], "auth.revokeUrl", problems, {
+        query: false,
+    });
+    const revokeMethod = auth["revokeMethod"];
+    if (revokeMethod !== undefined &&
+        revokeMethod !== "POST" &&
+        revokeMethod !== "DELETE") {
+        problems.push({
+            path: "auth.revokeMethod",
+            message: "must be POST or DELETE",
+        });
+    }
+    if (revokeMethod !== undefined && revoke === undefined) {
+        problems.push({ path: "auth.revokeMethod", message: "needs a revokeUrl" });
+    }
+    const clientId = settingName(auth["clientId"], "auth.clientId", problems);
+    const clientSecret = auth["clientSecret"] === undefined
+        ? undefined
+        : settingName(auth["clientSecret"], "auth.clientSecret", problems);
+    if (clientSecret !== undefined && clientSecret === clientId) {
+        problems.push({
+            path: "auth.clientSecret",
+            message: "must be another setting than auth.clientId",
+        });
+    }
+    const inject = auth["inject"] ?? "form";
+    if (!INJECTIONS.includes(inject)) {
+        problems.push({
+            path: "auth.inject",
+            message: "must be form (the client in the body) or basic (HTTP Basic)",
+        });
+    }
+    const pkce = auth["pkce"] ?? true;
+    if (typeof pkce !== "boolean") {
+        problems.push({ path: "auth.pkce", message: "must be true or false" });
+    }
+    const separator = auth["scopeSeparator"] ?? "space";
+    if (!SEPARATORS.includes(separator)) {
+        problems.push({
+            path: "auth.scopeSeparator",
+            message: `must be one of ${SEPARATORS.join(", ")}`,
+        });
+    }
+    const prefix = endpoint(auth["scopePrefix"], "auth.scopePrefix", problems, {
+        query: false,
+    });
+    if (prefix && !prefix.url.endsWith("/")) {
+        problems.push({
+            path: "auth.scopePrefix",
+            message: "must end in / (https://www.googleapis.com/auth/): an app's scope is joined onto it",
+        });
+    }
+    const authorizeParams = stringMap(auth["authorizeParams"], "auth.authorizeParams", problems, (name, at) => {
+        if (!PARAM_NAME.test(name)) {
+            problems.push({ path: at, message: "must be a query parameter name" });
+        }
+        if (RESERVED_AUTHORIZE_PARAMS.includes(name)) {
+            problems.push({
+                path: at,
+                message: name === "include_granted_scopes"
+                    ? "include_granted_scopes would widen the token beyond the app's scopes; the Gateway never sends it"
+                    : `${name} is a parameter the Gateway sets itself`,
+            });
+        }
+    });
+    const tokenHeaders = stringMap(auth["tokenHeaders"], "auth.tokenHeaders", problems, (name, at) => {
+        if (!HEADER_NAME.test(name)) {
+            problems.push({ path: at, message: "must be a header name" });
+        }
+        else if (RESERVED_TOKEN_HEADERS.has(name.toLowerCase()) ||
+            name.toLowerCase().startsWith("x-everyapp-")) {
+            problems.push({
+                path: at,
+                message: `${name} is a header the Gateway sets itself`,
+            });
+        }
+    });
+    const parsedIdentity = identity(auth["identity"], common.hosts, problems);
+    const tolerated = scopeList(auth["tolerated"], "auth.tolerated", problems);
+    if (!authorize ||
+        !token ||
+        clientId === undefined ||
+        typeof pkce !== "boolean" ||
+        !SEPARATORS.includes(separator) ||
+        !INJECTIONS.includes(inject)) {
+        return undefined;
+    }
+    const flow = {
+        authorizeUrl: authorize.url,
+        tokenUrl: token.url,
+        ...(revoke === undefined ? {} : { revokeUrl: revoke.url }),
+        ...(revokeMethod === undefined
+            ? {}
+            : { revokeMethod: revokeMethod }),
+        inject: inject,
+        pkce,
+        scopeSeparator: separator,
+        ...(prefix === undefined ? {} : { scopePrefix: prefix.url }),
+        ...(authorizeParams === undefined ? {} : { authorizeParams }),
+        ...(tokenHeaders === undefined ? {} : { tokenHeaders }),
+        ...(parsedIdentity === undefined
+            ? {}
+            : { identity: parsedIdentity.identity }),
+        identityScopes: parsedIdentity?.scopes ?? [],
+        tolerated: tolerated ?? [],
+    };
+    const capability = oauthCapabilityOf(common, {
+        clientId,
+        ...(clientSecret === undefined ? {} : { clientSecret }),
+    }, flow);
+    const hosts = [...common.hosts];
+    for (const host of [authorize.host, token.host, revoke?.host]) {
+        if (host && !hosts.includes(host))
+            hosts.push(host);
+    }
+    return { capability, hosts };
+}
+function oauthCapabilityOf(common, secrets, flow) {
+    return {
+        mode: "oauth_client",
+        label: common.name,
+        secrets,
+        console: common.docs,
+        api: [...common.hosts],
+        flow,
+        ...(common.description === undefined
+            ? {}
+            : { description: common.description }),
+        ...(common.reference === undefined ? {} : { reference: common.reference }),
+        ...(common.hint === undefined ? {} : { hint: common.hint }),
+        ...(common.example === undefined ? {} : { example: common.example }),
+        ...(common.tags === undefined ? {} : { tags: common.tags }),
+    };
+}
+/**
+ * A spec already known to be good (a built-in, checked by its test) as
+ * its capability, without the parse: what the catalog runs at load, where
+ * calling the full parser would be an import cycle.
+ */
+export function oauthCapabilityFromSpec(spec) {
+    const { auth } = spec;
+    const flow = {
+        authorizeUrl: auth.authorizeUrl,
+        tokenUrl: auth.tokenUrl,
+        ...(auth.revokeUrl === undefined ? {} : { revokeUrl: auth.revokeUrl }),
+        ...(auth.revokeMethod === undefined
+            ? {}
+            : { revokeMethod: auth.revokeMethod }),
+        inject: auth.inject ?? "form",
+        pkce: auth.pkce ?? true,
+        scopeSeparator: auth.scopeSeparator ?? "space",
+        ...(auth.scopePrefix === undefined
+            ? {}
+            : { scopePrefix: auth.scopePrefix }),
+        ...(auth.authorizeParams === undefined
+            ? {}
+            : { authorizeParams: { ...auth.authorizeParams } }),
+        ...(auth.tokenHeaders === undefined
+            ? {}
+            : { tokenHeaders: { ...auth.tokenHeaders } }),
+        ...(auth.identity === undefined
+            ? {}
+            : {
+                identity: {
+                    url: auth.identity.url,
+                    label: auth.identity.label,
+                    ...(auth.identity.id === undefined ? {} : { id: auth.identity.id }),
+                },
+            }),
+        identityScopes: [...(auth.identity?.scopes ?? [])],
+        tolerated: [...(auth.tolerated ?? [])],
+    };
+    return oauthCapabilityOf({
+        id: spec.id,
+        name: spec.name,
+        docs: spec.docs,
+        hosts: spec.hosts,
+        ...(spec.description === undefined
+            ? {}
+            : { description: spec.description }),
+        ...(spec.api === undefined ? {} : { reference: spec.api }),
+        ...(spec.hint === undefined ? {} : { hint: spec.hint }),
+        ...(spec.example === undefined ? {} : { example: spec.example }),
+        ...(spec.tags === undefined ? {} : { tags: spec.tags }),
+    }, {
+        clientId: auth.clientId,
+        ...(auth.clientSecret === undefined
+            ? {}
+            : { clientSecret: auth.clientSecret }),
+    }, flow);
+}
+/**
+ * The JSON spec of an OAuth capability (`provider show`, a preset's round
+ * trip): `parseProviderSpec` of it gives the capability back.
+ */
+export function oauthSpecOf(id, capability) {
+    const { flow } = capability;
+    const identity = flow.identity === undefined
+        ? undefined
+        : {
+            ...flow.identity,
+            ...(flow.identityScopes.length === 0
+                ? {}
+                : { scopes: [...flow.identityScopes] }),
+        };
+    return {
+        id,
+        name: capability.label,
+        ...(capability.description === undefined
+            ? {}
+            : { description: capability.description }),
+        docs: capability.console,
+        ...(capability.reference === undefined
+            ? {}
+            : { api: capability.reference }),
+        hosts: [...capability.api],
+        auth: {
+            kind: "oauth2-user",
+            authorizeUrl: flow.authorizeUrl,
+            tokenUrl: flow.tokenUrl,
+            ...(flow.revokeUrl === undefined ? {} : { revokeUrl: flow.revokeUrl }),
+            ...(flow.revokeMethod === undefined
+                ? {}
+                : { revokeMethod: flow.revokeMethod }),
+            clientId: capability.secrets.clientId,
+            ...(capability.secrets.clientSecret === undefined
+                ? {}
+                : { clientSecret: capability.secrets.clientSecret }),
+            inject: flow.inject,
+            pkce: flow.pkce,
+            scopeSeparator: flow.scopeSeparator,
+            ...(flow.scopePrefix === undefined
+                ? {}
+                : { scopePrefix: flow.scopePrefix }),
+            ...(flow.authorizeParams === undefined
+                ? {}
+                : { authorizeParams: { ...flow.authorizeParams } }),
+            ...(flow.tokenHeaders === undefined
+                ? {}
+                : { tokenHeaders: { ...flow.tokenHeaders } }),
+            ...(identity === undefined ? {} : { identity }),
+            ...(flow.tolerated.length === 0
+                ? {}
+                : { tolerated: [...flow.tolerated] }),
+        },
+        ...(capability.hint === undefined ? {} : { hint: capability.hint }),
+        ...(capability.example === undefined
+            ? {}
+            : { example: capability.example }),
+        ...(capability.tags === undefined ? {} : { tags: [...capability.tags] }),
+    };
+}

package/dist/internal/protocol.d.ts

@@ -39,6 +39,15 @@ export declare const GATEWAY_ERROR_HEADER = "x-everyapp-error";
  * from what browsers send.
  */
 export declare const ORG_HEADER = "x-everyapp-org";
+/**
+ * On background work's call to an OAuth provider's API: the member whose
+ * connection to this app the call uses. Set by `for: { background: true,
+ * userId }`; the gateway reads it on the held-token branch only, for an
+ * organization's own app, and the perimeter strips it, with every
+ * `x-everyapp-*`, from browsers. It addresses a connection; it is not a
+ * permission: connecting in the app already lets the app use it.
+ */
+export declare const USER_HEADER = "x-everyapp-user";
 /** 120-second lifetime — caps revocation staleness while surviving clock skew. */
 export declare const IDENTITY_TTL_SECONDS = 120;
 /** System tokens are minted per call and live at most a minute. */
@@ -63,14 +72,48 @@ export declare const ISSUER_ENV = "EVERYAPP_IDENTITY_ISSUER";
 export declare const SHARED_ENV = "EVERYAPP_SHARED";
 /** When set to `1` or `true` in the worker env, the dev identity kid is accepted. */
 export declare const DEV_ENV = "EVERYAPP_DEV";
+/**
+ * The organization an app's Worker is pinned to (a secret the deploy sends;
+ * in development the stub gateway's organization). `everyApp()` refuses an
+ * identity for any other organization; absent on a shared app's Workers.
+ */
+export declare const ORG_ID_ENV = "EVERY_APP_ORG_ID";
+/**
+ * The organization the dev gateway's seeded user belongs to. The same value
+ * as `@every-app/sdk/dev`'s, kept apart like {@link DEV_ISSUER} (the same
+ * test pins the two together).
+ */
+export declare const DEV_ORG_ID = "dev-org";
 /** `sub` claim the gateway mints public-route markers with. */
 export declare const PUBLIC_MARKER_SUB = "public";
 /** `sub` claim of gateway system tokens. */
 export declare const SYSTEM_TOKEN_SUB = "system";
+/**
+ * Linked dev (`everyapp dev --gateway`, docs/design/linked-dev.md): the
+ * dev Worker's env names the gateway-lite's loopback forwarder and the
+ * run's nonce, and the SDK builds a `{ fetch }` in place of the missing
+ * `EVERY_APP_GATEWAY` binding from them. Set by `everyAppWorker()` in a
+ * development build from the process environment `everyapp dev` starts
+ * the app with; never deployed.
+ */
+export declare const LINKED_DEV_URL_ENV = "EVERYAPP_LINKED_DEV_URL";
+export declare const LINKED_DEV_NONCE_ENV = "EVERYAPP_LINKED_DEV_NONCE";
+/** The header the forwarder requires, with the run's nonce: no simple cross-origin request can send it. */
+export declare const LINKED_DEV_HEADER = "x-everyapp-linked-dev";
+/** Where the gateway-lite serves the forwarder, under the app's own host. */
+export declare const LINKED_DEV_FORWARD_PATH = "/__everyapp/gateway";
 export type IdentityChannel = "web" | "api" | "mcp" | "agent";
+/**
+ * The channels a tool call arrives on: `mcp` for an AI client's MCP
+ * connection, `agent` for an agent principal the Gateway runs a call for.
+ * Only the ToolBus mints either with a `tc` claim.
+ */
+export declare const TOOL_CALL_CHANNELS: readonly IdentityChannel[];
+/** `act.sub` of an agent principal: `agent:<agt_id>`; `sub` stays its sponsor. */
+export declare const AGENT_ACTOR_PREFIX = "agent:";
 export type IdentityTokenType = "user" | "public" | "system";
 /** What a system token may open. One purpose per token. */
-export type SystemTokenPurpose = "tools.list";
+export type SystemTokenPurpose = "tools.list" | "events.deliver";
 /** The actor on whose behalf the request is made (user, MCP client, agent). */
 export interface IdentityActor {
     sub: string;
@@ -80,21 +123,59 @@ export interface IdentitySubject {
     email: string;
     orgId: string;
     orgRole: string;
+    /**
+     * The organization's name as its owners set it (`org_name`), so an app
+     * can show "Acme" rather than an id. Left out when the minter has none.
+     */
+    orgName?: string;
 }
+/**
+ * A member's role in the organization, as the identity token carries it.
+ * Owners and admins manage; anything the Gateway might mint that an app
+ * doesn't know is read as `member`.
+ */
+export type OrgRole = "owner" | "admin" | "member";
+/** `role` as an {@link OrgRole}: `owner` and `admin` as they are, anything else `member`. */
+export declare function toOrgRole(role: unknown): OrgRole;
+/** Whether `user` manages the organization: an owner or an admin. */
+export declare function isAdmin(user: {
+    orgRole: OrgRole | string;
+}): boolean;
+/**
+ * Whether an agent principal made this call: `chan: "agent"` with
+ * `act.sub` `agent:<agt_id>`. `user.id` is still the sponsoring member (the
+ * person accountable for the agent), so key rows by it as for anyone;
+ * `user.actor.sub` names the agent.
+ */
+export declare function isAgentCall(user: {
+    channel: IdentityChannel;
+    actor: IdentityActor;
+}): boolean;
 export interface EveryAppUser {
     /** User id (the `sub` claim). */
     id: string;
     email: string;
     orgId: string;
-    orgRole: string;
+    orgRole: OrgRole;
+    /**
+     * The organization's display name (the `org_name` claim), as its owners
+     * set it: trimmed, at most 64 characters, no control characters. Show
+     * it; never key data by it (names change, `orgId` doesn't). Undefined
+     * when the token carries none.
+     */
+    orgName?: string;
     channel: IdentityChannel;
-    /** The acting principal (user, or `mcp:<client>` / agent). */
+    /**
+     * The acting principal: the user id, the credential acting for them
+     * (`pat:<id>`, `oauth:<id>`, `access:<email>`), or an agent
+     * (`agent:<agt_id>`, on `channel: "agent"`; {@link isAgentCall}).
+     */
     actor: IdentityActor;
     scopes: string[];
     jti: string;
     /**
-     * Set only on an MCP tool call (`channel: "mcp"`): the one call this
-     * identity was minted for.
+     * Set only on a tool call (`channel: "mcp"` or `"agent"`): the one call
+     * this identity was minted for.
      */
     toolCall?: ToolCallClaim;
 }
@@ -103,6 +184,8 @@ export interface IdentityClaims extends JWTPayload {
     email: string;
     org_id: string;
     org_role: string;
+    /** The organization's display name; absent when the minter had none. */
+    org_name?: string;
     chan: IdentityChannel;
     act: IdentityActor;
     scopes: string[];
@@ -114,6 +197,11 @@ export interface SystemClaims extends JWTPayload {
     typ: "system";
     purpose: SystemTokenPurpose;
     jti: string;
+    /**
+     * `events.deliver` only: the SHA-256 (base64url) of the request body the
+     * token was minted for, so it opens that one delivery and nothing else.
+     */
+    bh?: string;
 }
 export interface PublicMarkerClaims extends JWTPayload {
     typ: "public";
@@ -185,7 +273,11 @@ export interface MintSystemTokenOptions {
     now?: number;
     /** Header kid. Defaults to the production kid; dev mints with the dev kid. */
     keyId?: string;
+    /** `events.deliver`: the body's SHA-256, base64url ({@link bodyHash}). */
+    bodyHash?: string;
 }
+/** SHA-256 of a request body, base64url: what an `events.deliver` token's `bh` names. */
+export declare function bodyHash(body: string): Promise<string>;
 /**
  * Mint the gateway's system token for `x-everyapp-system`: no user, one
  * purpose, one app, one minute. The SDK only accepts it on the endpoint its