@dewee/identity 0.0.0-stage → 0.1.0-beta.1

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# @dewee/identity
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Server SDK of Dewee Connect: sign your users in to a Dewee agent, answer the hosted-link handoff,
+report user lifecycle changes, and read the verified user inside your MCP server.
+
+- Server only. Every entry point refuses to run where `window` exists: it holds your application
+  secrets.
+- Node 20.3 or later, ESM. One dependency: [`jose`](https://github.com/panva/jose). Signing and
+  verification use WebCrypto, so the token format also works in Workers-style runtimes.
+- Secrets, tokens and assertions never appear in an error message or in `JSON.stringify(error)`.
+
+Status: beta (`0.x`). The contract follows the gateway's
+[OpenAPI spec](https://github.com/nextlevelbuilder/dewee/blob/dev/internal/http/openapi_spec.json) (tag `Identity`); a test fails when the two
+drift apart.
+
+Not published to npm yet. Until it is, build and pack it from this repository, then install the
+tarball in your app; once published, use `npm install @dewee/identity` instead.
+
+```sh
+pnpm install && pnpm --filter @dewee/identity build
+cd packages/dewee-identity && pnpm pack       # writes dewee-identity-<version>.tgz
+npm install /path/to/dewee-identity-<version>.tgz   # in your app
+```
+
+The full walkthrough, with curl equivalents for other languages, is the
+[Dewee Connect integration recipe](https://github.com/nextlevelbuilder/dewee/blob/dev/docs/dewee-connect-integration.md). A runnable app is in
+[`examples/identity-partner-sample`](https://github.com/nextlevelbuilder/dewee/blob/dev/examples/identity-partner-sample/README.md).
+
+## API
+
+| Function | Call |
+|----------|------|
+| `exchangeSession({gatewayUrl, signer, subject, agent, ttlSeconds?})` | `POST /v1/identity/sessions/exchange`. Returns `{sessionToken, header, sessionId, principalId, applicationId, agentId, expiresAt, testMode, testModeBanner?}`. Also accepts a ready `assertion` instead of `signer` and `subject`. |
+| `startLink({gatewayUrl, sessionToken, idempotencyKey?})` | `POST /v1/identity/links` (web-first). Returns the proof code and the chat accounts it can be sent to. |
+| `readConnectRequest(url, {connectBaseUrl})` | Reads and checks `dewee_txn` and `return_to` on your `connect_start_url`. |
+| `createConnectRedirect({signer, subject, connectBaseUrl, deweeTxn, returnTo, cspNonce?})` | Signs the handoff assertion and returns the auto-submitting POST form (`html`). A strict CSP blocks the inline submit unless you pass your page's `cspNonce`; the user then presses the Continue button. |
+| `lifecycle({gatewayUrl, signer, subject, event, scopes?})` | `POST /v1/identity/principals/lifecycle`: `suspend`, `reactivate`, `delete`, `scopes_changed`. |
+| `revokeSession({gatewayUrl, signer, subject, sessionId})` | `POST /v1/identity/sessions/{id}/revoke`. |
+| `logout({gatewayUrl, signer, subject, principalId})` | `POST /v1/identity/principals/{id}/logout`. |
+| `verifyTrustedUser(params, {mcpContextSecret, serverId, issuer, tenantId, applicationId, replayGuard?})` | Verifies `params._meta.dewee.trusted_user` in your MCP server and returns the user. |
+| `createAssertion({...signer, purpose, subject, ...})` | The signed assertion itself, for a call you make on your own. |
+
+A `signer` is `{applicationId, issuer, secret}` for an `hmac` application, or
+`{applicationId, issuer, privateKeyJwk, algorithm}` (RS256, ES256 or EdDSA, with a `kid`) for a
+`jwks` one. The `subject` is your stable user id: at most 255 bytes and never an email address.
+The SDK refuses any subject containing `@`, which is stricter than the gateway's email-shape check.
+
+`verifyTrustedUser` accepts each `jti` once. Its default `MemoryReplayGuard` keeps up to 100,000
+unexpired ids in process memory and fails closed when full (every new token is refused with reason
+`replay` until ids expire). Use it for development or a single process; in production pass a
+shared `replayGuard` (Redis `SET NX EX`, a database row with a unique key).
+
+Gateway calls take `gatewayUrl` (https, or http on localhost; `allowInsecureHttp` for a private
+network), `timeoutMs` (default 10000), `signal` and `fetch`.
+
+## Errors
+
+Every failure is a `DeweeIdentityError`:
+
+```ts
+try {
+  await exchangeSession(opts);
+} catch (err) {
+  if (err instanceof DeweeIdentityError) {
+    err.code;              // IDENTITY_REQUIRED, LINK_REVOKED, RESOURCE_EXHAUSTED, TRANSPORT_ERROR, ...
+    err.status;            // HTTP status, 0 when no answer arrived
+    err.remediation;       // {action, audience} for identity errors
+    err.retryAfterSeconds; // set on 429
+    err.retryable;         // true for rate limits and unavailable sources
+  }
+}
+```
+
+`verifyTrustedUser` refuses with `IDENTITY_REQUIRED` and a `reason` (`signature`, `audience`,
+`issuer`, `tenant`, `application`, `expired`, `replay`, and so on) for your logs. A missing
+verification setting is `INVALID_ARGUMENT`: all four bindings (server, issuer, tenant,
+application) are required.
+
+## Development
+
+```sh
+pnpm --filter @dewee/identity typecheck
+pnpm --filter @dewee/identity test             # unit and cross-language fixture tests
+pnpm --filter @dewee/identity lint             # build + publint --strict
+DEWEE_IT_GATEWAY_URL=http://127.0.0.1:18790 DEWEE_IT_GATEWAY_TOKEN=... \
+  pnpm --filter @dewee/identity test:integration   # against a live gateway with an agent "sdk-it"
+```
+
+The fixtures in `test/fixtures` are shared with the Go tests: `pnpm --filter @dewee/identity
+fixtures:generate` rewrites the SDK-signed assertions that `internal/identity/assertion` verifies,
+and `DEWEE_UPDATE_SDK_FIXTURES=1 go test ./internal/identity -run TestSDKTrustedUserFixture`
+rewrites the gateway-signed token the SDK verifies. All values in them are test-only.
+
+## License
+
+CC-BY-NC-4.0, as the rest of the repository.

package/dist/assertion.d.ts

@@ -0,0 +1,64 @@
+import { type JWK } from "jose";
+/** What an assertion is presented for. Each purpose has its own JWS `typ`, so one cannot replay as another. */
+export type AssertionPurpose = "session" | "handoff" | "lifecycle";
+/** JWS `typ` header of each purpose, as the gateway requires it. */
+export declare const ASSERTION_TYPES: Readonly<Record<AssertionPurpose, string>>;
+/** Asymmetric algorithms a `jwks` application may sign with. */
+export type AsymmetricAlgorithm = "RS256" | "ES256" | "EdDSA";
+/** Longest assertion lifetime the gateway accepts (exp - iat). */
+export declare const MAX_ASSERTION_TTL_SECONDS = 300;
+/** Default assertion lifetime. Assertions are single use; a short life is enough. */
+export declare const DEFAULT_ASSERTION_TTL_SECONDS = 60;
+/** Shortest HMAC assertion secret the gateway uses. */
+export declare const MIN_SECRET_LENGTH = 32;
+/**
+ * The partner application's signing identity. Create it once from your configuration and pass it
+ * to every call. Exactly one of `secret` (hmac application) or `privateKeyJwk` (jwks application)
+ * is set.
+ */
+export interface AssertionSigner {
+    /** The application id Dewee issued (`dewee identity setup` prints it). */
+    applicationId: string;
+    /** The issuer configured on the application, exactly. */
+    issuer: string;
+    /** The application's assertion secret (hmac mode). Keep it on your server. */
+    secret?: string;
+    /** A private JWK whose public half is in the application's `jwks_url` (jwks mode). Needs `kid`. */
+    privateKeyJwk?: JWK;
+    /** Algorithm of `privateKeyJwk`; defaults to the JWK's `alg`. */
+    algorithm?: AsymmetricAlgorithm;
+}
+export interface CreateAssertionOptions extends AssertionSigner {
+    purpose: AssertionPurpose;
+    /** Your stable, opaque user id. Never an email address: emails get reassigned. */
+    subject: string;
+    /** Required for `handoff`: the `dewee_txn` value Dewee passed to your connect start URL. */
+    nonce?: string;
+    /** Lifecycle only: the event the assertion reports. Leave it out for session revoke and logout. */
+    event?: LifecycleEvent;
+    /** Lifecycle only, with `scopes_changed`: the user's new scopes. */
+    scopes?: string[];
+    /** Lifetime in seconds, 1 to 300 (default 60). */
+    ttlSeconds?: number;
+    /** Clock override, for tests. */
+    now?: Date;
+    /** `jti` override, for tests. Every assertion must have a fresh one. */
+    jti?: string;
+}
+/** Principal lifecycle events a partner reports. */
+export type LifecycleEvent = "suspend" | "reactivate" | "delete" | "scopes_changed";
+/** The audience Dewee issued an application: `dewee:<application id>`. */
+export declare function applicationAudience(applicationId: string): string;
+/** Validates a UUID argument (lower-cased) and refuses the nil UUID. */
+export declare function requireUuid(value: unknown, name: string): string;
+/**
+ * Validates a subject the way the gateway does, a little stricter: non-empty, at most 255 bytes,
+ * and no `@`, so an email address can never key a user.
+ */
+export declare function requireSubject(subject: unknown): string;
+/**
+ * Signs a partner assertion: a compact JWS with `iss`, `aud` (`dewee:<application id>`), `sub`,
+ * `iat`, `exp` and a random `jti`, plus `nonce` for a handoff and `event`/`scopes` for a lifecycle
+ * report. Each assertion is accepted once.
+ */
+export declare function createAssertion(opts: CreateAssertionOptions): Promise<string>;

package/dist/assertion.js

@@ -0,0 +1,155 @@
+import { importJWK, SignJWT } from "jose";
+import { invalidArgument } from "./errors.js";
+import { assertServer } from "./transport.js";
+/** JWS `typ` header of each purpose, as the gateway requires it. */
+export const ASSERTION_TYPES = {
+    session: "dewee-session+jwt",
+    handoff: "dewee-handoff+jwt",
+    lifecycle: "dewee-lifecycle+jwt",
+};
+const ASYMMETRIC_ALGORITHMS = new Set(["RS256", "ES256", "EdDSA"]);
+/** Longest assertion lifetime the gateway accepts (exp - iat). */
+export const MAX_ASSERTION_TTL_SECONDS = 300;
+/** Default assertion lifetime. Assertions are single use; a short life is enough. */
+export const DEFAULT_ASSERTION_TTL_SECONDS = 60;
+/** Shortest HMAC assertion secret the gateway uses. */
+export const MIN_SECRET_LENGTH = 32;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const NIL_UUID = "00000000-0000-0000-0000-000000000000";
+const LIFECYCLE_EVENTS = new Set(["suspend", "reactivate", "delete", "scopes_changed"]);
+/** The audience Dewee issued an application: `dewee:<application id>`. */
+export function applicationAudience(applicationId) {
+    return `dewee:${applicationId.toLowerCase()}`;
+}
+/** Validates a UUID argument (lower-cased) and refuses the nil UUID. */
+export function requireUuid(value, name) {
+    if (typeof value !== "string" || !UUID_PATTERN.test(value) || value === NIL_UUID) {
+        throw invalidArgument(`${name} must be a UUID`);
+    }
+    return value.toLowerCase();
+}
+/**
+ * Validates a subject the way the gateway does, a little stricter: non-empty, at most 255 bytes,
+ * and no `@`, so an email address can never key a user.
+ */
+export function requireSubject(subject) {
+    if (typeof subject !== "string" || subject.trim() === "") {
+        throw invalidArgument("subject is required: your stable user id");
+    }
+    if (new TextEncoder().encode(subject).length > 255) {
+        throw invalidArgument("subject must be at most 255 bytes");
+    }
+    if (subject.includes("@")) {
+        throw invalidArgument("subject must be your stable opaque user id, not an email address");
+    }
+    return subject;
+}
+function requireIssuer(issuer) {
+    if (typeof issuer !== "string" || issuer.trim() === "" || issuer.length > 255 || /\s/.test(issuer)) {
+        throw invalidArgument("issuer is required: the issuer configured on the application, exactly");
+    }
+    return issuer;
+}
+/** Validates a signer and returns its key and algorithm. The key never leaves this module. */
+async function signingKey(signer) {
+    const hasSecret = signer.secret !== undefined;
+    const hasJwk = signer.privateKeyJwk !== undefined;
+    if (hasSecret === hasJwk) {
+        throw invalidArgument("set exactly one of secret (hmac application) or privateKeyJwk (jwks application)");
+    }
+    if (hasSecret) {
+        if (typeof signer.secret !== "string" || new TextEncoder().encode(signer.secret).length < MIN_SECRET_LENGTH) {
+            throw invalidArgument(`secret must be the application's assertion secret (at least ${MIN_SECRET_LENGTH} bytes)`);
+        }
+        // The gateway uses the secret's UTF-8 bytes as the HMAC key, exactly as issued (not decoded).
+        return { key: new TextEncoder().encode(signer.secret), alg: "HS256" };
+    }
+    const jwk = signer.privateKeyJwk;
+    if (jwk === null || typeof jwk !== "object" || typeof jwk.d !== "string") {
+        throw invalidArgument("privateKeyJwk must be a private JWK");
+    }
+    if (typeof jwk.kid !== "string" || jwk.kid === "") {
+        throw invalidArgument("privateKeyJwk needs a kid that matches the key in your jwks_url");
+    }
+    const alg = signer.algorithm ?? jwk.alg;
+    if (typeof alg !== "string" || !ASYMMETRIC_ALGORITHMS.has(alg)) {
+        throw invalidArgument("algorithm must be RS256, ES256 or EdDSA");
+    }
+    let key;
+    try {
+        key = await importJWK(jwk, alg);
+    }
+    catch {
+        throw invalidArgument(`privateKeyJwk is not a usable ${alg} private key`);
+    }
+    return { key, alg, kid: jwk.kid };
+}
+/** A random assertion id. */
+function newJti() {
+    return globalThis.crypto.randomUUID();
+}
+/**
+ * Signs a partner assertion: a compact JWS with `iss`, `aud` (`dewee:<application id>`), `sub`,
+ * `iat`, `exp` and a random `jti`, plus `nonce` for a handoff and `event`/`scopes` for a lifecycle
+ * report. Each assertion is accepted once.
+ */
+export async function createAssertion(opts) {
+    assertServer();
+    if (opts === null || typeof opts !== "object")
+        throw invalidArgument("options are required");
+    const typ = ASSERTION_TYPES[opts.purpose];
+    if (typ === undefined)
+        throw invalidArgument("purpose must be session, handoff or lifecycle");
+    const applicationId = requireUuid(opts.applicationId, "applicationId");
+    const issuer = requireIssuer(opts.issuer);
+    const subject = requireSubject(opts.subject);
+    const ttl = opts.ttlSeconds ?? DEFAULT_ASSERTION_TTL_SECONDS;
+    if (!Number.isInteger(ttl) || ttl < 1 || ttl > MAX_ASSERTION_TTL_SECONDS) {
+        throw invalidArgument(`ttlSeconds must be an integer from 1 to ${MAX_ASSERTION_TTL_SECONDS}`);
+    }
+    const claims = {};
+    if (opts.purpose === "handoff") {
+        if (typeof opts.nonce !== "string" || opts.nonce === "" || opts.nonce.length > 512) {
+            throw invalidArgument("a handoff assertion needs nonce: the dewee_txn value of the connect request");
+        }
+        claims.nonce = opts.nonce;
+    }
+    else if (opts.nonce !== undefined) {
+        throw invalidArgument("nonce is for handoff assertions only");
+    }
+    if (opts.purpose === "lifecycle") {
+        // A lifecycle assertion without an event authorizes session revoke and logout only: replayed
+        // at the lifecycle route it is refused, so it can never suspend or reactivate anyone.
+        if (opts.event !== undefined && !LIFECYCLE_EVENTS.has(opts.event)) {
+            throw invalidArgument("event must be suspend, reactivate, delete or scopes_changed");
+        }
+        if (opts.event !== undefined)
+            claims.event = opts.event;
+        if (opts.event === "scopes_changed") {
+            if (!Array.isArray(opts.scopes) || !opts.scopes.every((s) => typeof s === "string")) {
+                throw invalidArgument("scopes_changed needs scopes: an array of strings");
+            }
+            claims.scopes = [...opts.scopes];
+        }
+        else if (opts.scopes !== undefined) {
+            throw invalidArgument("scopes go with the scopes_changed event only");
+        }
+    }
+    else if (opts.event !== undefined || opts.scopes !== undefined) {
+        throw invalidArgument("event and scopes are for lifecycle assertions only");
+    }
+    const jti = opts.jti ?? newJti();
+    if (typeof jti !== "string" || jti === "" || jti.length > 255)
+        throw invalidArgument("jti must be a non-empty string");
+    const { key, alg, kid } = await signingKey(opts);
+    const iat = Math.floor((opts.now ?? new Date()).getTime() / 1000);
+    return new SignJWT(claims)
+        .setProtectedHeader(kid === undefined ? { alg, typ } : { alg, typ, kid })
+        .setIssuer(issuer)
+        .setAudience(applicationAudience(applicationId))
+        .setSubject(subject)
+        .setIssuedAt(iat)
+        .setExpirationTime(iat + ttl)
+        .setJti(jti)
+        .sign(key);
+}

package/dist/browser.d.ts

@@ -0,0 +1,3 @@
+/** Browser-only helpers. This entrypoint imports no signer or server secrets. */
+export { openJobAccess, JobAccessError } from "./job-access.js";
+export type { OpenJobAccessOptions, JobAccessErrorCode } from "./job-access.js";

package/dist/browser.js

@@ -0,0 +1,2 @@
+/** Browser-only helpers. This entrypoint imports no signer or server secrets. */
+export { openJobAccess, JobAccessError } from "./job-access.js";

package/dist/errors.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Typed errors of the Dewee identity SDK.
+ *
+ * Every failure the SDK reports is a {@link DeweeIdentityError}. Its message never carries a
+ * secret, an assertion, a session token or a subject: only the code, the HTTP status and the fixed
+ * sentence the gateway sent.
+ */
+/** The seven identity error codes of the gateway (`IdentityError.error.code` in the OpenAPI spec). */
+export declare const IDENTITY_ERROR_CODES: readonly ["IDENTITY_REQUIRED", "IDENTITY_LINK_REQUIRED", "IDENTITY_CONFLICT", "LINK_EXPIRED", "LINK_REVOKED", "PERMISSION_DENIED", "SOURCE_UNAVAILABLE"];
+export type IdentityErrorCode = (typeof IDENTITY_ERROR_CODES)[number];
+/** Generic gateway error codes the identity routes also answer with. */
+export declare const GATEWAY_ERROR_CODES: readonly ["INVALID_REQUEST", "NOT_FOUND", "FAILED_PRECONDITION", "ALREADY_EXISTS", "IDEMPOTENCY_KEY_INVALID", "IDEMPOTENCY_KEY_REUSED", "REQUEST_TOO_LARGE", "RESOURCE_EXHAUSTED", "UNAUTHORIZED", "UNAVAILABLE", "INTERNAL"];
+export type GatewayErrorCode = (typeof GATEWAY_ERROR_CODES)[number];
+/** Codes the SDK raises itself, before or instead of a gateway answer. */
+export declare const SDK_ERROR_CODES: readonly ["INVALID_ARGUMENT", "SERVER_ONLY", "TRANSPORT_ERROR", "INVALID_RESPONSE"];
+export type SdkErrorCode = (typeof SDK_ERROR_CODES)[number];
+export type DeweeIdentityErrorCode = IdentityErrorCode | GatewayErrorCode | SdkErrorCode;
+/** Remediation actions of the gateway (`IdentityError.error.remediation.action`). */
+export declare const REMEDIATION_ACTIONS: readonly ["send_connect_link", "ask_user_to_dm", "retry_later", "contact_admin", "reauthenticate"];
+export type RemediationAction = (typeof REMEDIATION_ACTIONS)[number];
+/** Who acts on a remediation (`IdentityError.error.remediation.audience`). */
+export declare const REMEDIATION_AUDIENCES: readonly ["end_user", "operator", "integrator"];
+export type RemediationAudience = (typeof REMEDIATION_AUDIENCES)[number];
+export interface Remediation {
+    action: RemediationAction;
+    audience: RemediationAudience;
+}
+/** Why {@link verifyTrustedUser} refused a token. Bounded, safe to log. */
+export type TrustedUserRefusal = "missing" | "malformed" | "algorithm" | "type" | "signature" | "audience" | "issuer" | "tenant" | "application" | "not_yet_valid" | "lifetime" | "expired" | "subject" | "jti" | "replay";
+/** What an integrator does about each identity code. English, for logs and integrator UIs. */
+export declare const IDENTITY_ERROR_HINTS: Readonly<Record<IdentityErrorCode, string>>;
+export declare function isIdentityErrorCode(code: unknown): code is IdentityErrorCode;
+export interface DeweeIdentityErrorInit {
+    code: DeweeIdentityErrorCode;
+    message: string;
+    /** HTTP status of the gateway answer; 0 when no answer was received. */
+    status?: number;
+    remediation?: Remediation;
+    /** Seconds to wait before retrying (429 `Retry-After`). */
+    retryAfterSeconds?: number;
+    /** Set by {@link verifyTrustedUser} only. */
+    reason?: TrustedUserRefusal;
+    cause?: unknown;
+}
+export declare class DeweeIdentityError extends Error {
+    readonly code: DeweeIdentityErrorCode;
+    readonly status: number;
+    readonly remediation: Remediation | undefined;
+    readonly retryAfterSeconds: number | undefined;
+    readonly reason: TrustedUserRefusal | undefined;
+    constructor(init: DeweeIdentityErrorInit);
+    /** True for one of the seven identity codes. */
+    get isIdentityError(): boolean;
+    /** True when the same request may succeed later without a change (429, 503, transport). */
+    get retryable(): boolean;
+    /** Never serialize anything but the safe fields. */
+    toJSON(): Record<string, unknown>;
+}
+export declare function invalidArgument(message: string): DeweeIdentityError;
+/**
+ * Builds the typed error of a non-2xx gateway answer. The body is either the identity error
+ * envelope `{error: {code, message, type: "identity_error", remediation}}` or the generic one
+ * `{error: {code, message}}`. An unknown code keeps the status-derived code, so a caller can always
+ * switch on it.
+ */
+export declare function errorFromResponse(status: number, body: unknown, retryAfter: string | null): DeweeIdentityError;

package/dist/errors.js

@@ -0,0 +1,174 @@
+/**
+ * Typed errors of the Dewee identity SDK.
+ *
+ * Every failure the SDK reports is a {@link DeweeIdentityError}. Its message never carries a
+ * secret, an assertion, a session token or a subject: only the code, the HTTP status and the fixed
+ * sentence the gateway sent.
+ */
+/** The seven identity error codes of the gateway (`IdentityError.error.code` in the OpenAPI spec). */
+export const IDENTITY_ERROR_CODES = [
+    "IDENTITY_REQUIRED",
+    "IDENTITY_LINK_REQUIRED",
+    "IDENTITY_CONFLICT",
+    "LINK_EXPIRED",
+    "LINK_REVOKED",
+    "PERMISSION_DENIED",
+    "SOURCE_UNAVAILABLE",
+];
+/** Generic gateway error codes the identity routes also answer with. */
+export const GATEWAY_ERROR_CODES = [
+    "INVALID_REQUEST",
+    "NOT_FOUND",
+    "FAILED_PRECONDITION",
+    "ALREADY_EXISTS",
+    "IDEMPOTENCY_KEY_INVALID",
+    "IDEMPOTENCY_KEY_REUSED",
+    "REQUEST_TOO_LARGE",
+    "RESOURCE_EXHAUSTED",
+    "UNAUTHORIZED",
+    "UNAVAILABLE",
+    "INTERNAL",
+];
+/** Codes the SDK raises itself, before or instead of a gateway answer. */
+export const SDK_ERROR_CODES = [
+    /** A caller argument is missing or invalid; nothing was sent. */
+    "INVALID_ARGUMENT",
+    /** The SDK was loaded in a browser. It holds partner secrets and must run on a server. */
+    "SERVER_ONLY",
+    /** The gateway could not be reached (DNS, TLS, connection reset, timeout). */
+    "TRANSPORT_ERROR",
+    /** The gateway answered with a body the SDK does not understand. */
+    "INVALID_RESPONSE",
+];
+/** Remediation actions of the gateway (`IdentityError.error.remediation.action`). */
+export const REMEDIATION_ACTIONS = [
+    "send_connect_link",
+    "ask_user_to_dm",
+    "retry_later",
+    "contact_admin",
+    "reauthenticate",
+];
+/** Who acts on a remediation (`IdentityError.error.remediation.audience`). */
+export const REMEDIATION_AUDIENCES = ["end_user", "operator", "integrator"];
+/** What an integrator does about each identity code. English, for logs and integrator UIs. */
+export const IDENTITY_ERROR_HINTS = {
+    IDENTITY_REQUIRED: "The proof was not accepted. Check the application id, issuer, secret, clock and that each assertion is used once.",
+    IDENTITY_LINK_REQUIRED: "The chat account is not linked yet. Dewee sends the user a Connect link.",
+    IDENTITY_CONFLICT: "The chat account is linked to another user. Nothing changed; unlink it there first.",
+    LINK_EXPIRED: "The link or session expired. Start again.",
+    LINK_REVOKED: "The user's access was revoked or suspended. Sign the user in again.",
+    PERMISSION_DENIED: "The user is verified but not allowed to do this.",
+    SOURCE_UNAVAILABLE: "Dewee could not check the identity, so it refused. Retry later.",
+};
+const IDENTITY_CODE_SET = new Set(IDENTITY_ERROR_CODES);
+const GATEWAY_CODE_SET = new Set(GATEWAY_ERROR_CODES);
+const ACTION_SET = new Set(REMEDIATION_ACTIONS);
+const AUDIENCE_SET = new Set(REMEDIATION_AUDIENCES);
+export function isIdentityErrorCode(code) {
+    return typeof code === "string" && IDENTITY_CODE_SET.has(code);
+}
+export class DeweeIdentityError extends Error {
+    code;
+    status;
+    remediation;
+    retryAfterSeconds;
+    reason;
+    constructor(init) {
+        super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
+        this.name = "DeweeIdentityError";
+        this.code = init.code;
+        this.status = init.status ?? 0;
+        this.remediation = init.remediation;
+        this.retryAfterSeconds = init.retryAfterSeconds;
+        this.reason = init.reason;
+    }
+    /** True for one of the seven identity codes. */
+    get isIdentityError() {
+        return isIdentityErrorCode(this.code);
+    }
+    /** True when the same request may succeed later without a change (429, 503, transport). */
+    get retryable() {
+        return (this.code === "RESOURCE_EXHAUSTED" ||
+            this.code === "SOURCE_UNAVAILABLE" ||
+            this.code === "UNAVAILABLE" ||
+            this.code === "TRANSPORT_ERROR");
+    }
+    /** Never serialize anything but the safe fields. */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            status: this.status,
+            message: this.message,
+            remediation: this.remediation,
+            retryAfterSeconds: this.retryAfterSeconds,
+            reason: this.reason,
+        };
+    }
+}
+export function invalidArgument(message) {
+    return new DeweeIdentityError({ code: "INVALID_ARGUMENT", message });
+}
+function parseRemediation(raw) {
+    if (raw === null || typeof raw !== "object")
+        return undefined;
+    const { action, audience } = raw;
+    if (typeof action === "string" && ACTION_SET.has(action) && typeof audience === "string" && AUDIENCE_SET.has(audience)) {
+        return { action: action, audience: audience };
+    }
+    return undefined;
+}
+function statusFallbackCode(status) {
+    switch (status) {
+        case 400:
+            return "INVALID_REQUEST";
+        case 401:
+            return "IDENTITY_REQUIRED";
+        case 403:
+            return "PERMISSION_DENIED";
+        case 404:
+            return "NOT_FOUND";
+        case 409:
+            return "FAILED_PRECONDITION";
+        case 413:
+            return "REQUEST_TOO_LARGE";
+        case 429:
+            return "RESOURCE_EXHAUSTED";
+        case 503:
+            return "UNAVAILABLE";
+        default:
+            return "INTERNAL";
+    }
+}
+/**
+ * Builds the typed error of a non-2xx gateway answer. The body is either the identity error
+ * envelope `{error: {code, message, type: "identity_error", remediation}}` or the generic one
+ * `{error: {code, message}}`. An unknown code keeps the status-derived code, so a caller can always
+ * switch on it.
+ */
+export function errorFromResponse(status, body, retryAfter) {
+    let code = statusFallbackCode(status);
+    let message = `Dewee answered HTTP ${status}`;
+    let remediation;
+    const envelope = body !== null && typeof body === "object" ? body.error : undefined;
+    if (envelope !== null && typeof envelope === "object") {
+        const e = envelope;
+        if (typeof e.code === "string" && (IDENTITY_CODE_SET.has(e.code) || GATEWAY_CODE_SET.has(e.code))) {
+            code = e.code;
+        }
+        if (typeof e.message === "string" && e.message.trim() !== "") {
+            message = `${code}: ${e.message.slice(0, 300)}`;
+        }
+        remediation = parseRemediation(e.remediation);
+    }
+    if (message.startsWith("Dewee answered")) {
+        message = `${code}: ${message}`;
+    }
+    let retryAfterSeconds;
+    if (retryAfter !== null) {
+        const n = Number.parseInt(retryAfter, 10);
+        if (Number.isFinite(n) && n >= 0)
+            retryAfterSeconds = n;
+    }
+    return new DeweeIdentityError({ code, message, status, remediation, retryAfterSeconds });
+}

package/dist/exchange.d.ts

@@ -0,0 +1,51 @@
+import { type AssertionSigner } from "./assertion.js";
+import { type GatewayOptions } from "./transport.js";
+/** Authorization scheme of partner server calls. */
+export declare const ASSERTION_AUTH_SCHEME = "Dewee-Assertion";
+/** Header that carries an identity session token on HTTP calls. */
+export declare const IDENTITY_SESSION_HEADER = "X-Dewee-Identity-Session";
+/** Bounds of an identity session lifetime. */
+export declare const MIN_SESSION_TTL_SECONDS = 60;
+export declare const MAX_SESSION_TTL_SECONDS = 43200;
+interface ExchangeCommon extends GatewayOptions {
+    /** The agent the session is for: its id or its key, in the application's tenant. */
+    agent: string;
+    /** Session lifetime, 60 to 43200 seconds (gateway default 3600). */
+    ttlSeconds?: number;
+}
+/** Exchange a ready assertion (`purpose: "session"`). */
+export interface ExchangeWithAssertion extends ExchangeCommon {
+    assertion: string;
+    /**
+     * Set for an oidc application: `assertion` is then the user's OIDC ID token, and this is the
+     * Dewee application id it is for.
+     */
+    oidcApplicationId?: string;
+}
+/** Sign a session assertion for `subject` and exchange it in one call. */
+export interface ExchangeWithSigner extends ExchangeCommon {
+    signer: AssertionSigner;
+    subject: string;
+}
+export type ExchangeSessionOptions = ExchangeWithAssertion | ExchangeWithSigner;
+/** An identity session. Hand `sessionToken` to the widget; never log it. */
+export interface IdentitySession {
+    sessionToken: string;
+    /** Header the token travels in on HTTP calls (`X-Dewee-Identity-Session`). */
+    header: string;
+    sessionId: string;
+    principalId: string;
+    applicationId: string;
+    agentId: string;
+    expiresAt: Date;
+    testMode: boolean;
+    /** Present for a test-mode application: show it wherever this session's data appears. */
+    testModeBanner?: string;
+}
+/**
+ * Exchanges a partner proof of one user for a short-lived identity session bound to one agent
+ * (`POST /v1/identity/sessions/exchange`). The tenant and application come from the verified
+ * assertion; nothing in the request names a user, tenant or role.
+ */
+export declare function exchangeSession(opts: ExchangeSessionOptions): Promise<IdentitySession>;
+export {};