@tdacorp/identity-client 0.1.0

package/dist/next.d.cts

@@ -0,0 +1,85 @@
+import { NextResponse, NextRequest } from 'next/server';
+import { c as TokenSet, I as IdTokenClaims } from './verify-BiGhwaIz.cjs';
+import { SealSecret } from './sealed.cjs';
+import '@tdacorp/identity-authz';
+import 'jose';
+
+interface CreateLoginRouteConfig {
+    issuer: string;
+    clientId: string;
+    redirectUri: string;
+    /** Space-separated OAuth scopes. Defaults to `"openid profile email
+     *  roles"` -- `roles` is included in the default because without it the
+     *  minted token carries no `roles` claim, and every `permits()` call
+     *  (`@tdacorp/identity-authz`) against that token then permanently
+     *  returns `indeterminate` with `reason: 'absent-claim'`, regardless of
+     *  what the caller is actually authorized to do. Override this down to
+     *  whatever scope is actually needed -- e.g. `"openid"` alone -- for a
+     *  consuming app that genuinely does not use RBAC. */
+    scope?: string;
+    /** Encrypts the transaction cookie; see `./sealed`'s `SealSecret`. Must be
+     *  the same value `createCallbackRoute` is configured with. */
+    cookieSecret: SealSecret;
+    transactionCookieName?: string;
+    /** Where to send the user after login completes. Defaults to reading a
+     *  `returnTo` search param off the incoming request. */
+    getReturnTo?: (request: NextRequest) => string | undefined;
+}
+/** Builds a GET Route Handler that starts the OIDC login: generates PKCE and
+ *  `state`, seals them (plus `returnTo`) into a short-lived cookie, and
+ *  redirects to the identity server's `authorization_endpoint`. */
+declare function createLoginRoute(config: CreateLoginRouteConfig): (request: NextRequest) => Promise<NextResponse>;
+/**
+ * Why `createCallbackRoute`'s handler could not complete the login, passed
+ * to `config.onError` (or rendered by the default handler as a 400 JSON
+ * body naming `code`).
+ *
+ * - `'provider_error'`: the identity server's redirect itself carried an
+ *   `error` param (the user denied consent, an invalid request, etc).
+ * - `'missing_code'` / `'missing_state'`: the callback request is missing a
+ *   `code` or `state` query param.
+ * - `'missing_transaction'`: the transaction cookie `createLoginRoute` set
+ *   was not presented, failed to decrypt, or has expired.
+ * - `'state_mismatch'`: the `state` param does not match the value stored
+ *   in the transaction cookie -- a CSRF check failure.
+ * - `'token_exchange_failed'`: the authorization code could not be
+ *   exchanged for a token set (see `TokenRequestError`).
+ * - `'token_verification_failed'`: the returned id_token failed
+ *   `verifyIdToken` (see `TokenVerificationError`).
+ */
+interface CallbackError {
+    code: 'provider_error' | 'missing_code' | 'missing_state' | 'missing_transaction' | 'state_mismatch' | 'token_exchange_failed' | 'token_verification_failed';
+    message: string;
+}
+interface CreateCallbackRouteConfig {
+    issuer: string;
+    clientId: string;
+    /** Omit for a public client authenticating via PKCE alone. */
+    clientSecret?: string;
+    redirectUri: string;
+    cookieSecret: SealSecret;
+    transactionCookieName?: string;
+    /** Defaults to `clientId`, correct for a standard login where this app is
+     *  its own audience. */
+    audience?: string;
+    authorizedParties?: string[];
+    /**
+     * Called once the code has been exchanged and the id_token verified. This
+     * package does not decide what happens next -- session creation, cookie
+     * choice, redirect target are the consuming app's own concerns -- so this
+     * callback's return value IS the route handler's response.
+     */
+    onSuccess: (tokens: TokenSet, claims: IdTokenClaims, ctx: {
+        returnTo?: string;
+    }) => NextResponse | Promise<NextResponse>;
+    /** Defaults to a bare 400 JSON error body naming `error.code`. */
+    onError?: (error: CallbackError) => NextResponse | Promise<NextResponse>;
+}
+/** Builds a GET Route Handler that finishes the OIDC login: unseals the
+ *  transaction cookie, checks `state`, exchanges the code, verifies the
+ *  returned id_token, then hands the verified identity to
+ *  `config.onSuccess` -- see that option's own docblock for why this
+ *  package stops there. */
+declare function createCallbackRoute(config: CreateCallbackRouteConfig): (request: NextRequest) => Promise<NextResponse>;
+
+export { type CallbackError, type CreateCallbackRouteConfig, type CreateLoginRouteConfig, createCallbackRoute, createLoginRoute };

package/dist/next.d.ts

@@ -0,0 +1,85 @@
+import { NextResponse, NextRequest } from 'next/server';
+import { c as TokenSet, I as IdTokenClaims } from './verify-BiGhwaIz.js';
+import { SealSecret } from './sealed.js';
+import '@tdacorp/identity-authz';
+import 'jose';
+
+interface CreateLoginRouteConfig {
+    issuer: string;
+    clientId: string;
+    redirectUri: string;
+    /** Space-separated OAuth scopes. Defaults to `"openid profile email
+     *  roles"` -- `roles` is included in the default because without it the
+     *  minted token carries no `roles` claim, and every `permits()` call
+     *  (`@tdacorp/identity-authz`) against that token then permanently
+     *  returns `indeterminate` with `reason: 'absent-claim'`, regardless of
+     *  what the caller is actually authorized to do. Override this down to
+     *  whatever scope is actually needed -- e.g. `"openid"` alone -- for a
+     *  consuming app that genuinely does not use RBAC. */
+    scope?: string;
+    /** Encrypts the transaction cookie; see `./sealed`'s `SealSecret`. Must be
+     *  the same value `createCallbackRoute` is configured with. */
+    cookieSecret: SealSecret;
+    transactionCookieName?: string;
+    /** Where to send the user after login completes. Defaults to reading a
+     *  `returnTo` search param off the incoming request. */
+    getReturnTo?: (request: NextRequest) => string | undefined;
+}
+/** Builds a GET Route Handler that starts the OIDC login: generates PKCE and
+ *  `state`, seals them (plus `returnTo`) into a short-lived cookie, and
+ *  redirects to the identity server's `authorization_endpoint`. */
+declare function createLoginRoute(config: CreateLoginRouteConfig): (request: NextRequest) => Promise<NextResponse>;
+/**
+ * Why `createCallbackRoute`'s handler could not complete the login, passed
+ * to `config.onError` (or rendered by the default handler as a 400 JSON
+ * body naming `code`).
+ *
+ * - `'provider_error'`: the identity server's redirect itself carried an
+ *   `error` param (the user denied consent, an invalid request, etc).
+ * - `'missing_code'` / `'missing_state'`: the callback request is missing a
+ *   `code` or `state` query param.
+ * - `'missing_transaction'`: the transaction cookie `createLoginRoute` set
+ *   was not presented, failed to decrypt, or has expired.
+ * - `'state_mismatch'`: the `state` param does not match the value stored
+ *   in the transaction cookie -- a CSRF check failure.
+ * - `'token_exchange_failed'`: the authorization code could not be
+ *   exchanged for a token set (see `TokenRequestError`).
+ * - `'token_verification_failed'`: the returned id_token failed
+ *   `verifyIdToken` (see `TokenVerificationError`).
+ */
+interface CallbackError {
+    code: 'provider_error' | 'missing_code' | 'missing_state' | 'missing_transaction' | 'state_mismatch' | 'token_exchange_failed' | 'token_verification_failed';
+    message: string;
+}
+interface CreateCallbackRouteConfig {
+    issuer: string;
+    clientId: string;
+    /** Omit for a public client authenticating via PKCE alone. */
+    clientSecret?: string;
+    redirectUri: string;
+    cookieSecret: SealSecret;
+    transactionCookieName?: string;
+    /** Defaults to `clientId`, correct for a standard login where this app is
+     *  its own audience. */
+    audience?: string;
+    authorizedParties?: string[];
+    /**
+     * Called once the code has been exchanged and the id_token verified. This
+     * package does not decide what happens next -- session creation, cookie
+     * choice, redirect target are the consuming app's own concerns -- so this
+     * callback's return value IS the route handler's response.
+     */
+    onSuccess: (tokens: TokenSet, claims: IdTokenClaims, ctx: {
+        returnTo?: string;
+    }) => NextResponse | Promise<NextResponse>;
+    /** Defaults to a bare 400 JSON error body naming `error.code`. */
+    onError?: (error: CallbackError) => NextResponse | Promise<NextResponse>;
+}
+/** Builds a GET Route Handler that finishes the OIDC login: unseals the
+ *  transaction cookie, checks `state`, exchanges the code, verifies the
+ *  returned id_token, then hands the verified identity to
+ *  `config.onSuccess` -- see that option's own docblock for why this
+ *  package stops there. */
+declare function createCallbackRoute(config: CreateCallbackRouteConfig): (request: NextRequest) => Promise<NextResponse>;
+
+export { type CallbackError, type CreateCallbackRouteConfig, type CreateLoginRouteConfig, createCallbackRoute, createLoginRoute };

package/dist/next.js

@@ -0,0 +1,129 @@
+import {
+  exchangeAuthorizationCode,
+  fetchDiscovery,
+  generateCodeChallenge,
+  generateCodeVerifier,
+  generateState,
+  verifyIdToken
+} from "./chunk-VJSMXIZB.js";
+import {
+  seal,
+  unseal
+} from "./chunk-KLXEPP4S.js";
+
+// src/next.ts
+import { NextResponse } from "next/server";
+var TRANSACTION_TTL_SECONDS = 600;
+var DEFAULT_TRANSACTION_COOKIE = "identity_oauth_txn";
+var TRANSACTION_PURPOSE = "identity-client:oauth-transaction";
+function transactionCookieOptions(maxAge) {
+  return {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+    path: "/",
+    maxAge
+  };
+}
+function createLoginRoute(config) {
+  return async function loginRoute(request) {
+    const state = generateState();
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = await generateCodeChallenge(codeVerifier);
+    const returnTo = config.getReturnTo?.(request) ?? request.nextUrl.searchParams.get("returnTo") ?? void 0;
+    const transaction = { state, codeVerifier, returnTo };
+    const sealedTransaction = await seal(transaction, {
+      secret: config.cookieSecret,
+      ttlSeconds: TRANSACTION_TTL_SECONDS,
+      purpose: TRANSACTION_PURPOSE
+    });
+    const discovery = await fetchDiscovery(config.issuer);
+    const authorizeUrl = new URL(discovery.authorization_endpoint);
+    authorizeUrl.searchParams.set("client_id", config.clientId);
+    authorizeUrl.searchParams.set("redirect_uri", config.redirectUri);
+    authorizeUrl.searchParams.set("response_type", "code");
+    authorizeUrl.searchParams.set("scope", config.scope ?? "openid profile email roles");
+    authorizeUrl.searchParams.set("state", state);
+    authorizeUrl.searchParams.set("code_challenge", codeChallenge);
+    authorizeUrl.searchParams.set("code_challenge_method", "S256");
+    const response = NextResponse.redirect(authorizeUrl);
+    response.cookies.set(
+      config.transactionCookieName ?? DEFAULT_TRANSACTION_COOKIE,
+      sealedTransaction,
+      transactionCookieOptions(TRANSACTION_TTL_SECONDS)
+    );
+    return response;
+  };
+}
+function defaultOnError(error) {
+  return NextResponse.json({ error: error.code, error_description: error.message }, { status: 400 });
+}
+function createCallbackRoute(config) {
+  return async function callbackRoute(request) {
+    const handleError = config.onError ?? defaultOnError;
+    const cookieName = config.transactionCookieName ?? DEFAULT_TRANSACTION_COOKIE;
+    const params = request.nextUrl.searchParams;
+    const providerError = params.get("error");
+    if (providerError) {
+      return handleError({ code: "provider_error", message: params.get("error_description") ?? providerError });
+    }
+    const code = params.get("code");
+    const state = params.get("state");
+    if (!code) return handleError({ code: "missing_code", message: "Callback request has no code parameter" });
+    if (!state) return handleError({ code: "missing_state", message: "Callback request has no state parameter" });
+    const sealedTransaction = request.cookies.get(cookieName)?.value;
+    if (!sealedTransaction) {
+      return handleError({
+        code: "missing_transaction",
+        message: `No ${cookieName} cookie was presented; it may have expired, or this is a replayed callback`
+      });
+    }
+    const transaction = await unseal(sealedTransaction, {
+      secret: config.cookieSecret,
+      purpose: TRANSACTION_PURPOSE
+    });
+    if (!transaction) {
+      return handleError({ code: "missing_transaction", message: "The transaction cookie failed to decrypt, or has expired" });
+    }
+    if (transaction.state !== state) {
+      return handleError({ code: "state_mismatch", message: "The state parameter does not match the value stored at login" });
+    }
+    let tokens;
+    try {
+      tokens = await exchangeAuthorizationCode({
+        issuer: config.issuer,
+        clientId: config.clientId,
+        clientSecret: config.clientSecret,
+        code,
+        redirectUri: config.redirectUri,
+        codeVerifier: transaction.codeVerifier
+      });
+    } catch (error) {
+      return handleError({
+        code: "token_exchange_failed",
+        message: error instanceof Error ? error.message : "Token exchange failed"
+      });
+    }
+    if (!tokens.idToken) {
+      return handleError({ code: "token_verification_failed", message: "Token response carried no id_token to verify" });
+    }
+    const verification = await verifyIdToken(tokens.idToken, {
+      issuer: config.issuer,
+      audience: config.audience ?? config.clientId,
+      authorizedParties: config.authorizedParties
+    });
+    if (!verification.success) {
+      return handleError({
+        code: "token_verification_failed",
+        message: verification.errors.map((e) => `${e.code}: ${e.message}`).join("; ")
+      });
+    }
+    const response = await config.onSuccess(tokens, verification.data, { returnTo: transaction.returnTo });
+    response.cookies.delete(cookieName);
+    return response;
+  };
+}
+export {
+  createCallbackRoute,
+  createLoginRoute
+};

package/dist/sealed.cjs

@@ -0,0 +1,101 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/sealed.ts
+var sealed_exports = {};
+__export(sealed_exports, {
+  MAX_SEALED_BYTES: () => MAX_SEALED_BYTES,
+  seal: () => seal,
+  unseal: () => unseal
+});
+module.exports = __toCommonJS(sealed_exports);
+var import_jose = require("jose");
+async function deriveContentEncryptionKey(secret, purpose) {
+  const encoder = new TextEncoder();
+  const keyMaterial = await crypto.subtle.importKey("raw", encoder.encode(secret), "HKDF", false, ["deriveBits"]);
+  const bits = await crypto.subtle.deriveBits(
+    { name: "HKDF", hash: "SHA-256", salt: new Uint8Array(0), info: encoder.encode(purpose) },
+    keyMaterial,
+    256
+  );
+  return new Uint8Array(bits);
+}
+function resolveSealingKey(secret) {
+  if (typeof secret === "string") return { secretValue: secret };
+  const keyNumbers = Object.keys(secret).map(Number);
+  if (keyNumbers.length === 0) throw new Error("seal: secret key-rotation map is empty");
+  const highest = Math.max(...keyNumbers);
+  return { kid: String(highest), secretValue: secret[highest] };
+}
+var MAX_SEALED_BYTES = 4096;
+async function seal(payload, options) {
+  const { kid, secretValue } = resolveSealingKey(options.secret);
+  const cek = await deriveContentEncryptionKey(secretValue, options.purpose);
+  const header = {
+    alg: "dir",
+    enc: "A256GCM",
+    ...kid !== void 0 ? { kid } : {}
+  };
+  const sealed = await new import_jose.EncryptJWT(payload).setProtectedHeader(header).setIssuedAt().setExpirationTime(`${options.ttlSeconds}s`).encrypt(cek);
+  const byteLength = new TextEncoder().encode(sealed).length;
+  if (byteLength > MAX_SEALED_BYTES) {
+    throw new Error(
+      `seal: sealed payload is ${byteLength} bytes, over the ${MAX_SEALED_BYTES}-byte limit (MAX_SEALED_BYTES). Shrink the payload -- do not chunk it across cookies; see MAX_SEALED_BYTES's own docblock for why.`
+    );
+  }
+  return sealed;
+}
+function resolveUnsealingKey(secret, kid) {
+  if (typeof secret === "string") return { secretValue: secret };
+  if (kid === void 0 || !(Number(kid) in secret)) return { reason: "unknown-key" };
+  return { secretValue: secret[Number(kid)] };
+}
+function classifyUnsealError(error) {
+  const code = error instanceof import_jose.errors.JOSEError ? error.code : void 0;
+  return code === "ERR_JWT_EXPIRED" ? "expired" : "invalid";
+}
+async function unseal(sealedValue, options) {
+  let kid;
+  try {
+    kid = (0, import_jose.decodeProtectedHeader)(sealedValue).kid;
+  } catch {
+    options.onError?.("invalid");
+    return null;
+  }
+  const resolved = resolveUnsealingKey(options.secret, kid);
+  if ("reason" in resolved) {
+    options.onError?.(resolved.reason);
+    return null;
+  }
+  try {
+    const cek = await deriveContentEncryptionKey(resolved.secretValue, options.purpose);
+    const { payload } = await (0, import_jose.jwtDecrypt)(sealedValue, cek);
+    return payload;
+  } catch (error) {
+    const reason = classifyUnsealError(error);
+    options.onError?.(reason);
+    return null;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MAX_SEALED_BYTES,
+  seal,
+  unseal
+});

package/dist/sealed.d.cts

@@ -0,0 +1,95 @@
+import { JWTPayload } from 'jose';
+
+/**
+ * The key material `seal()`/`unseal()` derive a content-encryption key from.
+ *
+ * A plain string is the common case: one secret, used for every seal and
+ * unseal. A `Record<number, string>` is a rotation map -- `seal()` always
+ * encrypts under the highest-numbered key (the active one) and stamps that
+ * number into the JWE header as `kid`; `unseal()` reads `kid` back off the
+ * header to pick the matching key, so values sealed under a retired key
+ * keep decrypting while new ones move to the new key. The same `secret`
+ * value must be given to both `seal()` and `unseal()` for a given `purpose`.
+ */
+type SealSecret = string | Record<number, string>;
+/** Hard limit on a sealed value's own length, enforced by `seal()`.
+ *
+ * A sealed value that does not fit in one cookie must never be chunked
+ * across multiple `Set-Cookie` headers: the combined `Cookie` header the
+ * browser sends back on the NEXT request then risks exceeding common
+ * reverse-proxy request-header limits (nginx's default is 8KB total), which
+ * fails as an opaque HTTP 431 one layer removed from the actual cause -- a
+ * request that never reaches this application's own error handling at all.
+ * A hard throw here, at the point of creation, is far easier to debug than a
+ * 431 discovered in production weeks later. */
+declare const MAX_SEALED_BYTES = 4096;
+/** Options for `seal()`. */
+interface SealOptions {
+    /** The key material to encrypt under; see `SealSecret`'s own docblock for
+     *  the single-secret vs. rotation-map shapes. */
+    secret: SealSecret;
+    /** How long the sealed value stays valid, in seconds, before `unseal()`
+     *  reports it as `'expired'`. */
+    ttlSeconds: number;
+    /** Mixed into key derivation (see `deriveContentEncryptionKey`) so the
+     *  same base secret used for two different purposes derives two
+     *  different keys. Must match the `purpose` passed to `unseal()`. */
+    purpose: string;
+}
+/**
+ * Encrypts `payload` into a compact JWE (`alg: "dir"`, `enc: "A256GCM"`)
+ * that expires after `ttlSeconds`.
+ *
+ * WHY REAL ENCRYPTION, NOT A SIGNATURE
+ *
+ * This is NOT justified by Edge-runtime compatibility -- the session
+ * boundary this package's `./next` subpath is designed to sit alongside
+ * runs the Node runtime, not Edge, so that argument does not hold here and
+ * this module makes no such claim.
+ *
+ * It is justified by wanting real encryption (JWE, not a signed-but-legible
+ * JWT) for a payload that might carry something sensitive -- an OAuth
+ * transaction's PKCE verifier, a `returnTo` URL, an admin session's extra
+ * claim -- so the cookie's contents are opaque to whoever holds the cookie,
+ * not just tamper-evident. This is the same caution Next.js's own general
+ * cookie guidance gives regardless of encryption: minimize what a cookie
+ * payload carries in the first place. Encryption here is defense in depth on
+ * top of that, not a reason to stop minimizing.
+ *
+ * See `deriveContentEncryptionKey` for why `purpose` is mixed into key
+ * derivation. Throws synchronously if the result would exceed
+ * `MAX_SEALED_BYTES` -- see that constant's docblock for why this is a
+ * throw, not a truncation or a chunking scheme.
+ *
+ * @param payload - The data to encrypt. Any JWT-payload-shaped object.
+ * @param options - See `SealOptions`.
+ * @returns The compact JWE string to store (e.g. as a cookie value).
+ */
+declare function seal(payload: JWTPayload, options: SealOptions): Promise<string>;
+/** Why `unseal` could not produce a payload. `onError` (on `UnsealOptions`)
+ *  receives exactly this, so a caller can log or alarm on `'invalid'`
+ *  (tampering, or the wrong secret) differently from routine `'expired'`. */
+type UnsealFailureReason = 'expired' | 'invalid' | 'unknown-key';
+/** Options for `unseal()`. */
+interface UnsealOptions {
+    /** Must be the same value `seal()` was called with for this sealed value
+     *  (or, for a rotation map, still contain the key it was sealed under). */
+    secret: SealSecret;
+    /** Must match the `purpose` `seal()` was called with; a mismatch fails
+     *  decryption the same way tampering does. */
+    purpose: string;
+    /** Called with the specific reason `unseal()` returned `null`, so a
+     *  caller can log or alarm on `'invalid'` differently from routine
+     *  `'expired'`. */
+    onError?: (reason: UnsealFailureReason) => void;
+}
+/** Decrypts and returns a payload sealed by `seal()`, or `null` on ANY
+ *  failure -- this never throws for an expected failure. `options.secret`
+ *  and `options.purpose` must match what `seal()` was called with; `kid` is
+ *  read from the sealed value's own header to pick the right key out of a
+ *  rotation map (see `resolveUnsealingKey`). Pass `onError` to be told WHICH
+ *  kind of failure this was, without having to treat every `null` the same
+ *  way. */
+declare function unseal<T = JWTPayload>(sealedValue: string, options: UnsealOptions): Promise<T | null>;
+
+export { MAX_SEALED_BYTES, type SealOptions, type SealSecret, type UnsealFailureReason, type UnsealOptions, seal, unseal };

package/dist/sealed.d.ts

@@ -0,0 +1,95 @@
+import { JWTPayload } from 'jose';
+
+/**
+ * The key material `seal()`/`unseal()` derive a content-encryption key from.
+ *
+ * A plain string is the common case: one secret, used for every seal and
+ * unseal. A `Record<number, string>` is a rotation map -- `seal()` always
+ * encrypts under the highest-numbered key (the active one) and stamps that
+ * number into the JWE header as `kid`; `unseal()` reads `kid` back off the
+ * header to pick the matching key, so values sealed under a retired key
+ * keep decrypting while new ones move to the new key. The same `secret`
+ * value must be given to both `seal()` and `unseal()` for a given `purpose`.
+ */
+type SealSecret = string | Record<number, string>;
+/** Hard limit on a sealed value's own length, enforced by `seal()`.
+ *
+ * A sealed value that does not fit in one cookie must never be chunked
+ * across multiple `Set-Cookie` headers: the combined `Cookie` header the
+ * browser sends back on the NEXT request then risks exceeding common
+ * reverse-proxy request-header limits (nginx's default is 8KB total), which
+ * fails as an opaque HTTP 431 one layer removed from the actual cause -- a
+ * request that never reaches this application's own error handling at all.
+ * A hard throw here, at the point of creation, is far easier to debug than a
+ * 431 discovered in production weeks later. */
+declare const MAX_SEALED_BYTES = 4096;
+/** Options for `seal()`. */
+interface SealOptions {
+    /** The key material to encrypt under; see `SealSecret`'s own docblock for
+     *  the single-secret vs. rotation-map shapes. */
+    secret: SealSecret;
+    /** How long the sealed value stays valid, in seconds, before `unseal()`
+     *  reports it as `'expired'`. */
+    ttlSeconds: number;
+    /** Mixed into key derivation (see `deriveContentEncryptionKey`) so the
+     *  same base secret used for two different purposes derives two
+     *  different keys. Must match the `purpose` passed to `unseal()`. */
+    purpose: string;
+}
+/**
+ * Encrypts `payload` into a compact JWE (`alg: "dir"`, `enc: "A256GCM"`)
+ * that expires after `ttlSeconds`.
+ *
+ * WHY REAL ENCRYPTION, NOT A SIGNATURE
+ *
+ * This is NOT justified by Edge-runtime compatibility -- the session
+ * boundary this package's `./next` subpath is designed to sit alongside
+ * runs the Node runtime, not Edge, so that argument does not hold here and
+ * this module makes no such claim.
+ *
+ * It is justified by wanting real encryption (JWE, not a signed-but-legible
+ * JWT) for a payload that might carry something sensitive -- an OAuth
+ * transaction's PKCE verifier, a `returnTo` URL, an admin session's extra
+ * claim -- so the cookie's contents are opaque to whoever holds the cookie,
+ * not just tamper-evident. This is the same caution Next.js's own general
+ * cookie guidance gives regardless of encryption: minimize what a cookie
+ * payload carries in the first place. Encryption here is defense in depth on
+ * top of that, not a reason to stop minimizing.
+ *
+ * See `deriveContentEncryptionKey` for why `purpose` is mixed into key
+ * derivation. Throws synchronously if the result would exceed
+ * `MAX_SEALED_BYTES` -- see that constant's docblock for why this is a
+ * throw, not a truncation or a chunking scheme.
+ *
+ * @param payload - The data to encrypt. Any JWT-payload-shaped object.
+ * @param options - See `SealOptions`.
+ * @returns The compact JWE string to store (e.g. as a cookie value).
+ */
+declare function seal(payload: JWTPayload, options: SealOptions): Promise<string>;
+/** Why `unseal` could not produce a payload. `onError` (on `UnsealOptions`)
+ *  receives exactly this, so a caller can log or alarm on `'invalid'`
+ *  (tampering, or the wrong secret) differently from routine `'expired'`. */
+type UnsealFailureReason = 'expired' | 'invalid' | 'unknown-key';
+/** Options for `unseal()`. */
+interface UnsealOptions {
+    /** Must be the same value `seal()` was called with for this sealed value
+     *  (or, for a rotation map, still contain the key it was sealed under). */
+    secret: SealSecret;
+    /** Must match the `purpose` `seal()` was called with; a mismatch fails
+     *  decryption the same way tampering does. */
+    purpose: string;
+    /** Called with the specific reason `unseal()` returned `null`, so a
+     *  caller can log or alarm on `'invalid'` differently from routine
+     *  `'expired'`. */
+    onError?: (reason: UnsealFailureReason) => void;
+}
+/** Decrypts and returns a payload sealed by `seal()`, or `null` on ANY
+ *  failure -- this never throws for an expected failure. `options.secret`
+ *  and `options.purpose` must match what `seal()` was called with; `kid` is
+ *  read from the sealed value's own header to pick the right key out of a
+ *  rotation map (see `resolveUnsealingKey`). Pass `onError` to be told WHICH
+ *  kind of failure this was, without having to treat every `null` the same
+ *  way. */
+declare function unseal<T = JWTPayload>(sealedValue: string, options: UnsealOptions): Promise<T | null>;
+
+export { MAX_SEALED_BYTES, type SealOptions, type SealSecret, type UnsealFailureReason, type UnsealOptions, seal, unseal };

package/dist/sealed.js

@@ -0,0 +1,10 @@
+import {
+  MAX_SEALED_BYTES,
+  seal,
+  unseal
+} from "./chunk-KLXEPP4S.js";
+export {
+  MAX_SEALED_BYTES,
+  seal,
+  unseal
+};