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

package/dist/internal/oauthScopes.js

@@ -0,0 +1,416 @@
+/**
+ * The scope set names a manifest entry declares, or null when the entry
+ * voids its grant: `scopes` missing, not an array, empty, a non-string
+ * element, a name listed twice, or any name the policy doesn't offer. An
+ * unknown name voids the whole grant rather than narrowing it silently, so
+ * a newer CLI's set name reaching an older gateway is refused outright and
+ * a message can say so.
+ */
+export function declaredScopeSets(policy, entry) {
+    const declared = entry?.scopes;
+    if (!Array.isArray(declared) || declared.length === 0)
+        return null;
+    const names = [];
+    for (const name of declared) {
+        if (typeof name !== "string" ||
+            !Object.hasOwn(policy.sets, name) ||
+            names.includes(name)) {
+            return null;
+        }
+        names.push(name);
+    }
+    return names;
+}
+/**
+ * What an app with `sets` asks the provider for: the sets' scopes in
+ * registry order, deduplicated, then `alwaysRequested`. The status hands
+ * these out and the authorize URL (Microsoft: the token leg too) carries
+ * them verbatim.
+ */
+export function requestedScopes(policy, sets) {
+    const scopes = [];
+    const userScopes = [];
+    for (const [, set] of declaredSets(policy, sets)) {
+        pushNew(scopes, set.scopes);
+        pushNew(userScopes, set.userScopes ?? []);
+    }
+    pushNew(scopes, policy.alwaysRequested);
+    return { scopes, userScopes };
+}
+/**
+ * What a token an app with `sets` is handed may carry: the requested
+ * scopes and the tolerated ones, in the dialect's canonical spelling so a
+ * granted list canonicalised the same way compares exactly.
+ */
+export function allowedScopes(policy, sets) {
+    const requested = requestedScopes(policy, sets);
+    return {
+        scopes: canonical(policy.dialect, [
+            ...requested.scopes,
+            ...policy.tolerated,
+        ]),
+        userScopes: canonical(policy.dialect, requested.userScopes),
+    };
+}
+/**
+ * Whether a token response body carries a token: an access, refresh or ID
+ * token, or Slack's user token under `authed_user`. A 2xx without one
+ * (Slack's `ok: false`) is an error the app must see, not a grant.
+ */
+export function carriesToken(json) {
+    const body = record(json);
+    if (!body)
+        return false;
+    return (typeof body["access_token"] === "string" ||
+        typeof body["refresh_token"] === "string" ||
+        typeof body["id_token"] === "string" ||
+        typeof record(body["authed_user"])?.["access_token"] === "string");
+}
+/**
+ * The scopes a token response says it granted, canonicalised per dialect,
+ * or null when the answer names none for a token it carries, which fails
+ * closed: every documented success response of the three providers names
+ * them (map-providers: Google and Microsoft `scope`, Slack `scope` and
+ * `authed_user.scope`), so a missing field is an answer the gateway can't
+ * hold to anything.
+ */
+export function grantedScopes(policy, json) {
+    const body = record(json);
+    if (!body)
+        return null;
+    switch (policy.dialect) {
+        case "google": {
+            // Space-delimited, case-sensitive strings (Google's own words).
+            const scopes = splitScopes("google", body["scope"]);
+            return scopes ? { scopes } : null;
+        }
+        case "microsoft": {
+            // Documented URL-encoded with the Graph prefix
+            // (`https%3A%2F%2Fgraph.microsoft.com%2Fmail.read`), seen as short
+            // names in either case; `offline_access` is never echoed, and dropped
+            // if it ever is.
+            if (typeof body["scope"] !== "string")
+                return null;
+            let decoded;
+            try {
+                decoded = decodeURIComponent(body["scope"]);
+            }
+            catch {
+                return null;
+            }
+            const scopes = splitScopes("microsoft", decoded)?.filter((scope) => scope !== "offline_access");
+            return scopes && scopes.length > 0 ? { scopes } : null;
+        }
+        case "slack":
+            return slackGrantedScopes(body);
+    }
+}
+/**
+ * Slack answers with up to two tokens, each with its own scopes: the bot
+ * token at the top level and the installing person's under `authed_user`.
+ * Which kind the top-level one is comes from `token_type`, because a
+ * token-rotation refresh of a user token comes back at the top level with
+ * `token_type: "user"`; `authed_user` is a user token unless it says so.
+ */
+function slackGrantedScopes(body) {
+    const granted = {};
+    const take = (token, kind) => {
+        if (kind !== "bot" && kind !== "user")
+            return false;
+        const scopes = splitScopes("slack", token["scope"]);
+        if (!scopes)
+            return false;
+        const key = kind === "bot" ? "scopes" : "userScopes";
+        granted[key] = pushNew(granted[key] ?? [], scopes);
+        return true;
+    };
+    if (typeof body["access_token"] === "string") {
+        if (!take(body, body["token_type"]))
+            return null;
+    }
+    const authedUser = record(body["authed_user"]);
+    if (authedUser && typeof authedUser["access_token"] === "string") {
+        if (!take(authedUser, authedUser["token_type"] ?? "user"))
+            return null;
+    }
+    return granted.scopes || granted.userScopes ? granted : null;
+}
+/**
+ * What `granted` carries beyond `allowed`, per token kind, for a refusal's
+ * message and log line: the user token's extras as `user:<scope>`. Both
+ * lists are in the dialect's canonical spelling already.
+ */
+export function scopeExcess(granted, allowed) {
+    const extra = (scopes, within) => (scopes ?? []).filter((scope) => !within.includes(scope));
+    return [
+        ...extra(granted.scopes, allowed.scopes),
+        ...extra(granted.userScopes, allowed.userScopes).map((scope) => `user:${scope}`),
+    ];
+}
+/**
+ * The scopes a token request itself asks for (`scope`, and Slack's
+ * `user_scope`, in any case) in its form or JSON body, canonicalised per
+ * dialect for comparison with `allowedScopes()`, or null when the body
+ * names none. The query string is never read: the gateway refuses a
+ * request that puts these there, so only one place decides.
+ */
+export function requestedTokenScopes(policy, request) {
+    const fields = bodyFields(request);
+    if (!fields)
+        return null;
+    const requested = {};
+    const scopes = splitScopes(policy.dialect, fields["scope"]);
+    if (scopes)
+        requested.scopes = scopes;
+    const userScopes = splitScopes(policy.dialect, fields["user_scope"]);
+    if (userScopes)
+        requested.userScopes = userScopes;
+    return requested.scopes || requested.userScopes ? requested : null;
+}
+/**
+ * `request` with its `scope`, in any case, as the policy's `requestScope`
+ * says: replaced by the requested list of the app's `sets`, dropped, or
+ * kept as sent. A separate step after `injectClientCredentials()`, whose
+ * re-serialised form or JSON body this edits the same way; any other body
+ * is left alone.
+ */
+export function rewriteTokenRequestScope(policy, sets, request) {
+    if (policy.requestScope === "keep" || !request.body)
+        return request;
+    const replacement = policy.requestScope === "replace"
+        ? requestedScopes(policy, sets).scopes.join(" ")
+        : null;
+    const type = mediaType(request.headers.get("content-type"));
+    // Every spelling goes, as `injectClientCredentials()` strips the client:
+    // Entra reads a form's names in any case, so a `Scope` left beside the
+    // gateway's `scope` is refused upstream as a duplicate, or read instead.
+    const isScope = (name) => name.toLowerCase() === "scope";
+    let body = request.body;
+    if (type === FORM) {
+        const params = new URLSearchParams(body);
+        for (const name of new Set([...params.keys()].filter(isScope))) {
+            params.delete(name);
+        }
+        if (replacement !== null)
+            params.set("scope", replacement);
+        body = params.toString();
+    }
+    else if (type === JSON_TYPE) {
+        const parsed = jsonObject(body);
+        if (!parsed)
+            return request;
+        for (const name of Object.keys(parsed)) {
+            if (isScope(name))
+                delete parsed[name];
+        }
+        if (replacement !== null)
+            parsed["scope"] = replacement;
+        body = JSON.stringify(parsed);
+    }
+    else {
+        return request;
+    }
+    return { url: request.url, headers: request.headers, body };
+}
+/**
+ * The declared set that unlocks `method upstream`, or null. Not wired to
+ * any live path yet: it becomes the proxy's boundary once the gateway
+ * holds tokens, and the outbound Worker's for dispatched apps before that.
+ *
+ * In order: https only; the host must be on one of the declared sets'
+ * routes; the raw pathname is refused when it holds `\`, `//` or `%00`;
+ * each raw segment, and each percent-decoding of it while a `%` remains
+ * (a provider's layers may each decode once), is refused when it won't
+ * decode, holds a control or format character or a backslash, is one of
+ * the policy's denied segments in any case, or splits on `/` into a dot
+ * segment: `.` or `..`, with or without a `;` parameter (`..;x`), which
+ * Google's front end resolves like the bare one. The denied comparison is
+ * of the whole segment, because an encoded slash is part of one id to the
+ * provider, never a separator: a Search Console site URL whose own path
+ * holds `batch` stays matchable, and `2%2FmeasurementProtocolSecrets` is
+ * a data stream id that doesn't exist, not the secrets. Then the raw
+ * pathname, case preserved, is matched: GET and HEAD need a `paths` entry
+ * (exact, or a prefix when it ends in `/`), POST needs a `posts` pattern,
+ * and no other method goes through. Matching the raw path is what lets
+ * Search Console's `sites/https%3A%2F%2Fexample.com%2F/searchAnalytics/query`
+ * match `[^/]+` while `..`, batch tunnels and secrets stay refused however
+ * encoded. `X-HTTP-Method-Override`, `access_token` and `token` parameters
+ * are the proxy's to strip before it asks; nothing here reads them. The
+ * proxy fetches with `redirect: "manual"`: Google answers a dot segment it
+ * resolves with a 302 to the resolved path, and following one would carry
+ * the token to a path this never matched.
+ */
+export function scopeRouteAllows(policy, sets, method, upstream) {
+    if (upstream.protocol !== "https:")
+        return null;
+    const onHost = declaredSets(policy, sets).flatMap(([name, set]) => set.routes
+        .filter((route) => route.host === upstream.host)
+        .map((route) => [name, route]));
+    if (onHost.length === 0)
+        return null;
+    const pathname = upstream.pathname;
+    if (!safeSegments(policy, pathname))
+        return null;
+    const verb = method.toUpperCase();
+    for (const [name, route] of onHost) {
+        if (verb === "GET" || verb === "HEAD") {
+            const covered = route.paths.some((entry) => entry.endsWith("/") ? pathname.startsWith(entry) : pathname === entry);
+            if (covered)
+                return name;
+        }
+        else if (verb === "POST") {
+            if (route.posts?.some((pattern) => pattern.test(pathname)))
+                return name;
+        }
+    }
+    return null;
+}
+/** Control and format characters: in no provider's path once decoded. */
+const UNPRINTABLE = /[\p{Cc}\p{Cf}]/u;
+/** A dot segment, bare or with a path parameter (`..;x`): Google's front end resolves both. */
+const DOT_SEGMENT = /^\.{1,2}(;|$)/;
+/**
+ * Whether every segment of the raw `pathname` passes the checks above in
+ * each form a provider's layers could see it: raw, then decoded again
+ * while a `%` remains.
+ */
+function safeSegments(policy, pathname) {
+    if (pathname.includes("\\") ||
+        pathname.includes("//") ||
+        pathname.includes("%00")) {
+        return false;
+    }
+    const denied = policy.deniedSegments.map((segment) => segment.toLowerCase());
+    for (const raw of pathname.split("/")) {
+        let text = raw;
+        for (;;) {
+            if (!safeSegment(text, denied))
+                return false;
+            if (!text.includes("%"))
+                break;
+            // A `%` left after a decode is a byte the provider may decode again
+            // (double encoding), so that form is checked too; one that isn't an
+            // escape (`%2525` ends in a bare `%`) won't decode and refuses, as a
+            // malformed escape in the raw path does.
+            try {
+                text = decodeURIComponent(text);
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Whether one form of a segment is safe: no control or format character,
+ * no backslash (in no provider's grammar), not a denied segment in any
+ * case, and no dot segment among its `/`-split parts (a traversal the
+ * provider might resolve). The denied comparison is of the whole: an
+ * encoded slash is part of one id to the provider, never a separator, so
+ * a Search Console site URL whose own path holds `batch` stays matchable.
+ */
+function safeSegment(text, denied) {
+    if (UNPRINTABLE.test(text) || text.includes("\\"))
+        return false;
+    if (denied.includes(text.toLowerCase()))
+        return false;
+    return !text.split("/").some((part) => DOT_SEGMENT.test(part));
+}
+/** The policy's sets in registry order, keeping those `names` declares. */
+function declaredSets(policy, names) {
+    return Object.entries(policy.sets).filter(([name]) => names.includes(name));
+}
+const GOOGLE_ALIASES = new Map([
+    ["email", "https://www.googleapis.com/auth/userinfo.email"],
+    ["profile", "https://www.googleapis.com/auth/userinfo.profile"],
+]);
+const GRAPH_PREFIX = /^https:\/\/graph\.microsoft\.com\//i;
+/** `scopes` in the dialect's one spelling, deduplicated, order kept. */
+function canonical(dialect, scopes) {
+    return pushNew([], scopes.map((scope) => {
+        switch (dialect) {
+            case "google":
+                return GOOGLE_ALIASES.get(scope) ?? scope;
+            case "microsoft":
+                return scope.replace(GRAPH_PREFIX, "").toLowerCase();
+            case "slack":
+                return scope;
+        }
+    }));
+}
+/**
+ * A provider's scope field split into scopes, canonicalised, or null when
+ * it isn't a string or names nothing. Google and Microsoft separate with
+ * spaces; Slack with commas (spaces too, in its legacy form).
+ */
+function splitScopes(dialect, value) {
+    if (typeof value !== "string")
+        return null;
+    const separator = dialect === "slack" ? /[,\s]+/ : /\s+/;
+    const scopes = canonical(dialect, value.split(separator).filter(Boolean));
+    return scopes.length > 0 ? scopes : null;
+}
+/** `into` with each of `more` it doesn't have yet, in order. */
+function pushNew(into, more) {
+    for (const item of more)
+        if (!into.includes(item))
+            into.push(item);
+    return into;
+}
+const FORM = "application/x-www-form-urlencoded";
+const JSON_TYPE = "application/json";
+/** A token request's body fields, form or JSON, by lowercased name; null for any other body. */
+function bodyFields(request) {
+    if (!request.body)
+        return null;
+    const type = mediaType(request.headers.get("content-type"));
+    if (type === FORM)
+        return foldFields(new URLSearchParams(request.body));
+    if (type === JSON_TYPE) {
+        const parsed = jsonObject(request.body);
+        return parsed && foldFields(Object.entries(parsed));
+    }
+    return null;
+}
+/**
+ * `pairs` by lowercased name, as Entra reads a form's names in any case. A
+ * name's values are one space-joined list, so a field sent twice, or as
+ * `scope` and `Scope`, hides nothing in the second copy; a value that
+ * isn't a string leaves its field not a string, which reads as naming
+ * none.
+ */
+function foldFields(pairs) {
+    const fields = new Map();
+    for (const [name, value] of pairs) {
+        const key = name.toLowerCase();
+        const before = fields.get(key);
+        fields.set(key, !fields.has(key)
+            ? value
+            : typeof before === "string" && typeof value === "string"
+                ? `${before} ${value}`
+                : [before, value]);
+    }
+    return Object.fromEntries(fields);
+}
+/** A Content-Type's media type, lowercased and without parameters. */
+function mediaType(contentType) {
+    return (contentType ?? "").split(";")[0].trim().toLowerCase();
+}
+/**
+ * `text` as a JSON object, or null for anything else (an array, a scalar,
+ * not JSON). Shared with the gateway's read of a provider's token answer.
+ */
+export function jsonObject(text) {
+    try {
+        return record(JSON.parse(text));
+    }
+    catch {
+        return null;
+    }
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}

package/dist/internal/organizationName.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The rule for a workspace's name: what the Gateway's setup claim gives
+ * the first organization, what a personal organization is called, and
+ * what a rename takes (Manage workspace → Rename, `everyapp workspace
+ * rename`). The Gateway and the CLI share it so a name the CLI writes is
+ * one the Gateway would have accepted. A name is user input that reaches
+ * other people: the invitation emails it sends, and every member's
+ * organization switcher.
+ */
+export declare const MAX_ORGANIZATION_NAME_LENGTH = 64;
+/**
+ * The name, trimmed and with its runs of whitespace made single spaces, or
+ * null when it is empty, longer than 64 characters, or has a control or
+ * invisible formatting character (line breaks, bidirectional overrides,
+ * zero-width characters) anywhere in it.
+ */
+export declare function validOrganizationName(raw: string): string | null;
+//# sourceMappingURL=organizationName.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"organizationName.d.ts","sourceRoot":"","sources":["../../src/internal/organizationName.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAE/C;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKhE"}

package/dist/internal/organizationName.js

@@ -0,0 +1,24 @@
+/**
+ * The rule for a workspace's name: what the Gateway's setup claim gives
+ * the first organization, what a personal organization is called, and
+ * what a rename takes (Manage workspace → Rename, `everyapp workspace
+ * rename`). The Gateway and the CLI share it so a name the CLI writes is
+ * one the Gateway would have accepted. A name is user input that reaches
+ * other people: the invitation emails it sends, and every member's
+ * organization switcher.
+ */
+export const MAX_ORGANIZATION_NAME_LENGTH = 64;
+/**
+ * The name, trimmed and with its runs of whitespace made single spaces, or
+ * null when it is empty, longer than 64 characters, or has a control or
+ * invisible formatting character (line breaks, bidirectional overrides,
+ * zero-width characters) anywhere in it.
+ */
+export function validOrganizationName(raw) {
+    if (/[\p{Cc}\p{Cf}\u2028\u2029]/u.test(raw))
+        return null;
+    const name = raw.trim().replace(/\s+/g, " ");
+    if (!name || [...name].length > MAX_ORGANIZATION_NAME_LENGTH)
+        return null;
+    return name;
+}

package/dist/internal/protocol.d.ts

@@ -0,0 +1,195 @@
+/**
+ * @every-app/sdk/internal — Every App platform protocol internals.
+ *
+ * This subpath is for the Every App platform itself (gateway, perimeter, CLI),
+ * not for app authors. It owns the wire constants, claim shapes, claim codecs,
+ * and gateway-side JWT minters shared by the platform packages.
+ */
+import { type JWTPayload } from "jose";
+import type { ToolCallClaim } from "./tools.js";
+export declare const IDENTITY_ALG = "RS256";
+export declare const IDENTITY_KEY_ID = "everyapp-identity";
+export declare const IDENTITY_DEV_KEY_ID = "everyapp-identity-dev";
+/**
+ * The only issuer a dev-kid token may name. The same value as
+ * `@every-app/sdk/dev`'s, kept apart so the Worker never loads the module
+ * `cloudflare.config.ts` does (a test pins the two together).
+ */
+export declare const DEV_ISSUER = "https://gateway.dev.localhost";
+export declare const IDENTITY_HEADER = "x-everyapp-identity";
+export declare const PUBLIC_HEADER = "x-everyapp-public";
+/**
+ * Carries the gateway's system token on its own calls to an app (the tools
+ * catalog fetch). Never an identity: no user, and it only opens the endpoint
+ * named by its `purpose` claim.
+ */
+export declare const SYSTEM_HEADER = "x-everyapp-system";
+/**
+ * On a refusal the AppGateway binding makes itself (the app's manifest lacks
+ * the capability, the gateway holds no key), as opposed to the provider's
+ * own answer passed through: the refusal's code, also in the JSON body.
+ */
+export declare const GATEWAY_ERROR_HEADER = "x-everyapp-error";
+/**
+ * On a shared app's call to the AppGateway binding for work no request
+ * started (a cron, a Workflow step): the organization the work is for. The
+ * gateway believes it only from a shared app's Worker, and only for an
+ * active organization with a live member; an organization's own app may
+ * only name its own. The perimeter strips it, with every `x-everyapp-*`,
+ * from what browsers send.
+ */
+export declare const ORG_HEADER = "x-everyapp-org";
+/** 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. */
+export declare const SYSTEM_TOKEN_TTL_SECONDS = 60;
+/** Env var carrying the app's manifest id. */
+export declare const APP_ID_ENV = "EVERYAPP_APP_ID";
+/**
+ * Env var carrying the expected identity audience: the app's Worker name,
+ * which the gateway stamps as `aud` on every token it mints for the app. Two
+ * Workers of one app id (two organizations' copies) never accept each
+ * other's tokens.
+ */
+export declare const AUDIENCE_ENV = "EVERYAPP_AUDIENCE";
+/** Default env var carrying a JSON array of SPKI PEM public keys. */
+export declare const PUBLIC_KEYS_ENV = "EVERYAPP_IDENTITY_PUBLIC_KEYS";
+/** Env var carrying the expected gateway issuer for user identity verification. */
+export declare const ISSUER_ENV = "EVERYAPP_IDENTITY_ISSUER";
+/**
+ * Env var set to `1` on a shared app's Workers (one Worker for every
+ * organization): a gateway call from them must say whom it is for.
+ */
+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";
+/** `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";
+export type IdentityChannel = "web" | "api" | "mcp" | "agent";
+export type IdentityTokenType = "user" | "public" | "system";
+/** What a system token may open. One purpose per token. */
+export type SystemTokenPurpose = "tools.list";
+/** The actor on whose behalf the request is made (user, MCP client, agent). */
+export interface IdentityActor {
+    sub: string;
+}
+export interface IdentitySubject {
+    sub: string;
+    email: string;
+    orgId: string;
+    orgRole: string;
+}
+export interface EveryAppUser {
+    /** User id (the `sub` claim). */
+    id: string;
+    email: string;
+    orgId: string;
+    orgRole: string;
+    channel: IdentityChannel;
+    /** The acting principal (user, or `mcp:<client>` / agent). */
+    actor: IdentityActor;
+    scopes: string[];
+    jti: string;
+    /**
+     * Set only on an MCP tool call (`channel: "mcp"`): the one call this
+     * identity was minted for.
+     */
+    toolCall?: ToolCallClaim;
+}
+export interface IdentityClaims extends JWTPayload {
+    typ: "user";
+    email: string;
+    org_id: string;
+    org_role: string;
+    chan: IdentityChannel;
+    act: IdentityActor;
+    scopes: string[];
+    jti: string;
+    /** Tool-call binding; only the gateway's ToolBus mints it. */
+    tc?: ToolCallClaim;
+}
+export interface SystemClaims extends JWTPayload {
+    typ: "system";
+    purpose: SystemTokenPurpose;
+    jti: string;
+}
+export interface PublicMarkerClaims extends JWTPayload {
+    typ: "public";
+    pub: true;
+    jti: string;
+}
+export declare class ProtocolClaimsError extends Error {
+    constructor(message: string);
+}
+export declare function identitySubjectToClaims(subject: IdentitySubject, opts: {
+    channel?: IdentityChannel;
+    actor?: IdentityActor;
+    scopes?: string[];
+    toolCall?: ToolCallClaim;
+    jti: string;
+}): IdentityClaims;
+export declare function identityClaimsToEveryAppUser(payload: JWTPayload): EveryAppUser;
+export declare function publicMarkerClaims(jti: string): PublicMarkerClaims;
+export declare function assertPublicMarkerClaims(payload: JWTPayload): void;
+/**
+ * A system token opens exactly one endpoint and lives at most
+ * {@link SYSTEM_TOKEN_TTL_SECONDS}: a leaked one is short-lived and useless
+ * anywhere else.
+ */
+export declare function assertSystemClaims(payload: JWTPayload, purpose: SystemTokenPurpose): SystemClaims;
+export interface MintIdentityOptions {
+    subject: IdentitySubject;
+    /** The app id this token is scoped to — becomes the `aud` claim. */
+    audience: string;
+    issuer: string;
+    channel?: IdentityChannel;
+    actor?: IdentityActor;
+    scopes?: string[];
+    /** Bind the token to one MCP tool call (`tc` claim). ToolBus only. */
+    toolCall?: ToolCallClaim;
+    ttlSeconds?: number;
+    now?: number;
+    /** Header kid. Defaults to the production kid; dev mints with the dev kid. */
+    keyId?: string;
+}
+/**
+ * Mint an identity JWT. Returns the compact JWS string to inject as
+ * `x-everyapp-identity`.
+ */
+export declare function mintIdentityJwt(privateKeyPem: string, opts: MintIdentityOptions): Promise<string>;
+export interface MintPublicMarkerOptions {
+    /** The app id this marker is scoped to — becomes the `aud` claim. */
+    audience: string;
+    issuer: string;
+    ttlSeconds?: number;
+    now?: number;
+    /** Header kid. Defaults to the production kid; dev mints with the dev kid. */
+    keyId?: string;
+}
+/**
+ * Mint the public-route marker for `x-everyapp-public`. A bare header value
+ * is never a trust source, so the marker is a signed, short-lived, app-scoped
+ * JWT with `pub: true` and `typ: "public"` that the SDK verifies exactly like
+ * an identity token.
+ */
+export declare function mintPublicMarkerJwt(privateKeyPem: string, opts: MintPublicMarkerOptions): Promise<string>;
+export interface MintSystemTokenOptions {
+    /** The app id the token is for — becomes the `aud` claim. */
+    audience: string;
+    issuer: string;
+    purpose: SystemTokenPurpose;
+    /** At most {@link SYSTEM_TOKEN_TTL_SECONDS}. */
+    ttlSeconds?: number;
+    now?: number;
+    /** Header kid. Defaults to the production kid; dev mints with the dev kid. */
+    keyId?: 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
+ * purpose names, and never as an identity.
+ */
+export declare function mintSystemJwt(privateKeyPem: string, opts: MintSystemTokenOptions): Promise<string>;
+//# sourceMappingURL=protocol.d.ts.map

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

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