@uniformdev/mesh-sdk 20.72.3-alpha.3 → 20.72.3-alpha.5

package/dist/server/index.d.mts

@@ -0,0 +1,386 @@
+import { ApiClient } from '@uniformdev/context/api';
+
+/** @deprecated This beta identity delegation API may change with breaking changes. */
+interface DelegationTokenClientOptions {
+    /** Uniform API host (e.g. 'https://uniform.app'). */
+    apiHost: string;
+    /** UUID of the integration definition. */
+    integrationId: string;
+    /** Plaintext app secret for this integration. */
+    integrationSecret: string;
+    /** Optional fetch implementation. Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/** @deprecated This beta identity delegation API may change with breaking changes. */
+interface DelegationTokenResponse {
+    /** Bearer access token that can be used to call Uniform APIs on behalf of the user. */
+    accessToken: string;
+    /** Refresh token for obtaining a new access token when the current one expires. Absent when the session was minted with `allowRefresh: false`. */
+    refreshToken?: string;
+    /** Always 'Bearer'. */
+    tokenType: 'Bearer';
+    /** Token lifetime in seconds. */
+    expiresIn: number;
+}
+/**
+ * Stable, low-detail kinds of token-exchange failures. Callers branch on these
+ * instead of parsing arbitrary upstream message text, and integrators surface a
+ * sanitised public message rather than whatever the server happened to return.
+ */
+type DelegationTokenErrorKind = 'bad_request' | 'unauthenticated' | 'forbidden' | 'not_found' | 'rate_limited' | 'server_error' | 'unknown';
+/** @deprecated This beta identity delegation API may change with breaking changes. */
+declare class DelegationTokenError extends Error {
+    readonly status: number;
+    readonly kind: DelegationTokenErrorKind;
+    constructor(status: number, kind: DelegationTokenErrorKind, publicMessage: string);
+}
+/**
+ * Maps an HTTP status code to a stable `DelegationTokenErrorKind`. Never
+ * propagate arbitrary upstream `errorMessage`/`error`/`message` body content.
+ * We are guarding against propagating attacker-influenced or sensitive upstream text
+ * out of /api/v1/token failures into integrator-side surfaces (logs, Sentry, integrator UI errors).
+ */
+declare function classifyDelegationTokenStatus(status: number): DelegationTokenErrorKind;
+/**
+ * Builds a sanitised {@link DelegationTokenError} for a non-OK token exchange response.
+ * The error body is intentionally ignored because it may contain attacker-controlled or
+ * upstream library text (token fragments, claim values, stack traces).
+ */
+declare function buildDelegationTokenError(status: number): DelegationTokenError;
+/**
+ * Server-side client for the Uniform token exchange endpoint.
+ * Use this in your integration's backend to exchange a session token (obtained from the
+ * Mesh SDK iframe context) for a delegation token, or to refresh an existing delegation token.
+ *
+ * Extends {@link ApiClient} to inherit concurrency limiting (limitPolicy) and 429 retry
+ * with exponential backoff (handleRateLimits). Auth credentials go in the POST body —
+ * the inherited header-based auth is intentionally unused.
+ *
+ * @deprecated This beta identity delegation API may change with breaking changes.
+ */
+declare class DelegationTokenClient extends ApiClient {
+    #private;
+    constructor(options: DelegationTokenClientOptions);
+    /**
+     * Exchanges a short-lived session token for a delegation token and refresh token.
+     * The session token is obtained by the integration's frontend via `sdk.getSessionToken()`.
+     *
+     * @deprecated This beta identity delegation API may change with breaking changes.
+     */
+    exchangeSessionToken(sessionToken: string): Promise<DelegationTokenResponse>;
+    /**
+     * Exchanges a refresh token for a new delegation token and a new refresh token.
+     *
+     * Replay posture: refresh tokens are bearer credentials that are valid until
+     * their server-side expiry. They are NOT single-use — a captured refresh token can be
+     * replayed by an attacker that also has the integration secret until it expires.
+     * Single-use enforcement (refresh-token storage, family/jti tracking, replay revocation)
+     * is tracked in `UNI-9279`.
+     *
+     * @deprecated This beta identity delegation API may change with breaking changes.
+     */
+    refreshDelegationToken(refreshToken: string): Promise<DelegationTokenResponse>;
+}
+
+/**
+ * Default cookie name for the JWE-sealed Mesh delegation session.
+ *
+ * Exported as a constant so partners can keep one source of truth across the
+ * BFF (`Set-Cookie` writer + `Cookie` reader) without introducing typos.
+ * Partners running multiple integration BFFs on the same host SHOULD pick a
+ * unique cookie name per integration (e.g. `__Host-uniform_mesh_delegation_<integrationId>`)
+ * and pass that explicitly to `serializeSessionCookie`/`parseCookies` lookups.
+ * Names with the `__Host-` prefix require `Path=/` and must not set `Domain`.
+ */
+declare const DELEGATION_COOKIE_NAME = "__Host-uniform_mesh_delegation";
+/**
+ * Default session TTL in seconds (8 hours). Shared between
+ * `sealDelegationSession` (JWE `exp` claim) and `serializeSessionCookie`
+ * (`Max-Age` attribute) so they cannot drift independently.
+ */
+declare const SESSION_TTL_SECONDS: number;
+
+/**
+ * Parse a raw `Cookie` request-header value into a name → value map.
+ *
+ * Wraps `cookie.parse` so consumers get RFC 6265 §5.4 behaviour: quoted
+ * values are unwrapped, URL-encoded values are decoded, and when the same
+ * name appears twice the FIRST occurrence wins (matching the user-agent's
+ * stored set semantics). `undefined` input returns `{}` so callers can pass
+ * `req.headers.cookie` directly without a null-check at every call site.
+ *
+ * The return type is `Record<string, string>`; the underlying parser may
+ * return `undefined` for malformed values, but the wrapper filters those
+ * out so consumers can rely on `cookies[NAME]` being either a string or
+ * absent (`in` check) without a `typeof` guard.
+ */
+declare function parseCookies(cookieHeader: string | undefined): Record<string, string>;
+
+/**
+ * Caller-tunable options for `serializeSessionCookie`.
+ *
+ * Cookie-flag invariants intentionally absent from this surface:
+ *   - `httpOnly`, `secure`, `sameSite` are always emitted with the values
+ *     the iframe-embedded mesh-app context requires. Any other choice is
+ *     silently broken in this deployment shape and is not configurable.
+ */
+type SerializeSessionCookieOptions = {
+    /**
+     * `Path` attribute. Defaults to `/` so the cookie attaches on every BFF
+     * route. Override to scope the cookie to a sub-path when the BFF lives
+     * under a known prefix (e.g. `/api/mesh/`).
+     */
+    path?: string;
+    /**
+     * `Max-Age` in seconds. Defaults to 8 hours, matching the refresh-token
+     * lifetime issued by the Uniform delegation token endpoint at the time of
+     * writing. Partners on a different refresh-token TTL should pass their
+     * value explicitly.
+     */
+    maxAge?: number;
+    /**
+     * Emit the `Partitioned` (CHIPS) attribute. Defaults to `true` because
+     * the mesh-app is loaded as a cross-site iframe and CHIPS keys the cookie
+     * to (our origin × top-level site), which gives per-embedding isolation
+     * and survives Chrome's third-party cookie phase-out.
+     *
+     * Browser support for `Partitioned` is not yet universal — Safari is
+     * partial as of 2026 (same as Sec-Fetch-Site it seems :-/).
+     */
+    partitioned?: boolean;
+};
+/**
+ * Build a `Set-Cookie` header value for the delegation session cookie.
+ *
+ * The following flags are HARDCODED because the iframe-embedded mesh-app
+ * context is invariant — any other configuration is silently broken:
+ *
+ *   - `HttpOnly`: JavaScript cannot read the cookie via `document.cookie`.
+ *   - `Secure`: cookie only flows over HTTPS. Dev MUST also be HTTPS
+ *     (`next dev --experimental-https`, self-signed cert for Express, etc.).
+ *   - `SameSite=None`: required so the browser attaches the cookie on
+ *     subresource requests from inside the cross-site iframe. With
+ *     `Lax`/`Strict` the cookie would be stored but not returned.
+ *
+ * `Partitioned` (CHIPS) is emitted by default; pass `partitioned: false`
+ * to suppress it for partners deploying to a single embedding host.
+ *
+ * The cookie value is URL-encoded by the underlying `cookie` package so
+ * the resulting header is RFC 6265 §4.1.1 compliant. JWE strings produced
+ * by `sealDelegationSession` only contain unreserved characters, so the
+ * encoding is a no-op for them but is essential when partners reuse the
+ * helper for any other payload.
+ */
+declare function serializeSessionCookie(name: string, value: string, opts?: SerializeSessionCookieOptions): string;
+
+/**
+ * Headers `verifyCsrf` consumes. Callers extract these from their framework
+ * request object — see the README "Quick start" section for Next.js and
+ * Express snippets.
+ */
+type CsrfInput = {
+    /** `Origin` request header. */
+    origin: string | undefined;
+    /** `Referer` request header. Used as fallback when `Origin` is absent. */
+    referer: string | undefined;
+    /** `Sec-Fetch-Site` request header. Chromium-only; absent on Safari/Firefox<90. */
+    secFetchSite: string | undefined;
+    /** Value of the custom CSRF header (default name `x-mesh-csrf`). */
+    customHeader: string | undefined;
+};
+/**
+ * Caller-supplied CSRF policy. The package never reads `process.env`; the
+ * allow-list lives in consumer code so a typo is loud at boot and so the
+ * package stays edge-runtime-safe.
+ */
+type CsrfConfig = {
+    /**
+     * Origins allowed to call state-changing endpoints. Typical wiring:
+     * `[process.env.UNIFORM_DASHBOARD_ORIGIN, process.env.SELF_ORIGIN]`.
+     * MUST be origin strings (`https://host[:port]`). Trailing slashes are
+     * stripped before comparison so a misconfigured env var does not silently
+     * disable the CSRF check for that origin.
+     */
+    allowedOrigins: readonly string[];
+    /**
+     * Dev-only escape hatch. When `true`, skip Origin/Referer validation and
+     * rely on the custom CSRF header alone. Defaults to `false`.
+     *
+     * Wire from the consumer's dev-mode indicator — e.g.
+     * `process.env.NODE_ENV === 'development'` or an explicit local-only env
+     * var. Chromium often omits `Origin` on `https://localhost` iframe
+     * subresource requests (https://issues.chromium.org/issues/40499674); this
+     * flag exists for that local mesh dev case, not for loopback hosts in
+     * general.
+     */
+    skipOriginValidation?: boolean;
+    /** Expected custom-header value. Defaults to `'1'`. */
+    headerValue?: string;
+    /**
+     * When `true`, also require `Sec-Fetch-Site: same-origin`. Defaults to
+     * `false` because Safari/Firefox<90 omit the header. Partners on a
+     * Chromium-only embedding host can flip this on for defence-in-depth.
+     */
+    requireSecFetchSite?: boolean;
+};
+/**
+ * Discriminated result so consumers can log specific failure modes for
+ * metrics without echoing the reason verbatim to clients.
+ */
+type CsrfResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'origin_mismatch' | 'origin_missing' | 'header_missing' | 'sec_fetch_site_mismatch';
+};
+
+/**
+ * Verify a request against the delegation BFF CSRF policy.
+ *
+ * Order of checks (first failure wins):
+ *
+ *   1. Origin in `allowedOrigins`. If `Origin` header is absent, parse the
+ *      origin from `Referer` and check that. If both are absent, accept
+ *      `Sec-Fetch-Site: same-origin` as proof the request came from the
+ *      server's own origin (this header is forbidden — browsers never let
+ *      JS set it). This handles the spec-correct case where browsers omit
+ *      `Origin` on same-origin GET/HEAD requests. Skipped entirely when
+ *      `skipOriginValidation` is `true` (dev-only; see `CsrfConfig`). If
+ *      none of the above apply and no origin signal is present, fail with
+ *      `origin_missing`.
+ *   2. Custom header presence + value match. Closes the classic
+ *      cross-origin-from-a-browser CSRF case via the no-CORS-preflight
+ *      property of non-safelisted headers.
+ *   3. `Sec-Fetch-Site === 'same-origin'` when `requireSecFetchSite: true`.
+ *      Defence-in-depth on Chromium-only deployments. NOT a substitute for
+ *      either earlier check — Safari and Firefox<90 omit the header, so
+ *      partners supporting those browsers MUST leave this off.
+ *
+ * The caller is responsible for responding `403` on `ok: false`. The
+ * `reason` is intended for server-side logging and metrics; do NOT echo it
+ * verbatim to the client if you want to avoid leaking which check failed
+ * to a probing attacker.
+ */
+declare function verifyCsrf(input: CsrfInput, config: CsrfConfig): CsrfResult;
+
+/**
+ * Token pair stored inside the encrypted delegation session cookie.
+ */
+type DelegationSession = {
+    /** Short-lived Bearer token for calling Uniform APIs on behalf of the user. */
+    accessToken: string;
+    /**
+     * Long-lived refresh token. `undefined` means the user gave "this session
+     * only" consent during the delegation handshake — the BFF must re-handshake
+     * via cross-frame communication when the access token expires; it cannot
+     * silently rotate.
+     */
+    refreshToken: string | undefined;
+    /** Unix epoch milliseconds when `accessToken` expires. */
+    expiresAt: number;
+};
+
+/**
+ * Returns `true` when `session.accessToken` will expire within `bufferMs`
+ * (defaults to 60 seconds). 60s gives the BFF enough runway to absorb
+ * network latency to the Uniform token endpoint and minor clock skew.
+ *
+ * Consumers call this before every upstream Uniform API call. When it
+ * returns `true`, the consumer's BFF route refreshes the token pair via
+ * `DelegationTokenClient.refreshDelegationToken` (consumer code, not in
+ * this package), reseals via `sealDelegationSession`, and writes a new
+ * `Set-Cookie` header on the response BEFORE issuing the API call.
+ */
+declare function needsRefresh(session: DelegationSession, bufferMs?: number): boolean;
+
+/**
+ * Encrypt a `DelegationSession` into an AES-256-GCM JWE string suitable for
+ * storage inside an `HttpOnly` cookie.
+ *
+ * Algorithm: `dir` (direct key agreement) + `A256GCM` (encryption).
+ *
+ * The 32-byte key is derived from the secret via HKDF-SHA-256 (see `deriveKey`).
+ * The JWE carries `iat` and `exp` claims (8h TTL); `unsealDelegationSession`
+ * fails decryption once `exp` has elapsed, which protects against replay of
+ * a stale cookie value extracted from logs or a CDN cache after rotation.
+ */
+declare function sealDelegationSession(session: DelegationSession, secret: string): Promise<string>;
+
+/**
+ * Decrypt a JWE cookie string back into a `DelegationSession`.
+ *
+ * Returns `null` (instead of throwing) for any failure mode:
+ *   - expired `exp` claim,
+ *   - tampered ciphertext / authentication-tag mismatch,
+ *   - wrong secret,
+ *   - malformed payload (`accessToken` missing or wrong type, etc.).
+ *
+ * Callers treat `null` as "no session" and respond accordingly. Validation
+ * errors are surfaced via `console.error` with metadata about field presence
+ * and types only — raw token values are NEVER logged so a malformed payload
+ * cannot leak bearer credentials into log destinations.
+ */
+declare function unsealDelegationSession(jwe: string, secret: string): Promise<DelegationSession | null>;
+
+/** Issuer (`iss`) claim on Uniform delegation access tokens. */
+declare const uniformDelegationIssuer = "uniform:delegation";
+/** Audience (`aud`) claim on Uniform delegation access tokens accepted by Uniform HTTP APIs. */
+declare const uniformApiAudience = "uniform:api";
+/** Resolves the public JWKS URL for delegation access token verification. */
+declare function getJwksUrl(origin?: string): string;
+
+/**
+ * Configuration for {@link verifyDelegationAccessToken}.
+ */
+interface VerifyDelegationTokenOptions {
+    /**
+     * Full URL to the delegation JWKS endpoint.
+     *
+     * Defaults to {@link getJwksUrl} (`https://uniform.app/delegation/.well-known/jwks.json`).
+     *
+     * @example getJwksUrl(process.env.UNIFORM_API_HOST)
+     */
+    jwksUrl?: string | URL;
+    /**
+     * Clock tolerance in seconds for `exp` / `nbf` validation.
+     * @default 2
+     */
+    clockToleranceSeconds?: number;
+}
+/** Verified claims from a Uniform delegation access token. */
+interface DelegationAccessTokenClaims {
+    /** User identifier of the delegating user (`sub`). */
+    sub: string;
+    /** Team that owns the integration installation. */
+    teamId: string;
+    /** Actor claim: which integration is acting on behalf of the user. */
+    act: {
+        /** Integration definition ID. */
+        sub: string;
+        /** Integration type slug. */
+        integration_type: string;
+    };
+    /** Token issued-at (epoch seconds). */
+    iat: number;
+    /** Token expiry (epoch seconds). */
+    exp: number;
+}
+
+/**
+ * Verifies a Uniform delegation access token against the public JWKS.
+ *
+ * Use when your BFF makes authorization decisions outside Uniform APIs. If your BFF only
+ * proxies requests with the bearer token, skip verification — Uniform validates on its side.
+ *
+ * @throws When signature, issuer, audience, or expiry validation fails.
+ *
+ * @example
+ * ```ts
+ * const claims = await verifyDelegationAccessToken(token, {
+ *   jwksUrl: getJwksUrl(process.env.UNIFORM_API_HOST),
+ * });
+ * ```
+ */
+declare function verifyDelegationAccessToken(token: string, options?: VerifyDelegationTokenOptions): Promise<DelegationAccessTokenClaims>;
+
+export { type CsrfConfig, type CsrfInput, type CsrfResult, DELEGATION_COOKIE_NAME, type DelegationAccessTokenClaims, type DelegationSession, DelegationTokenClient, type DelegationTokenClientOptions, DelegationTokenError, type DelegationTokenErrorKind, type DelegationTokenResponse, SESSION_TTL_SECONDS, type SerializeSessionCookieOptions, type VerifyDelegationTokenOptions, buildDelegationTokenError, classifyDelegationTokenStatus, getJwksUrl, needsRefresh, parseCookies, sealDelegationSession, serializeSessionCookie, uniformApiAudience, uniformDelegationIssuer, unsealDelegationSession, verifyCsrf, verifyDelegationAccessToken };