@atlasauth/backend 0.23.0 → 0.25.0

package/dist/migration-presets.d.ts

@@ -0,0 +1,156 @@
+/**
+ * ZERO-LOGOUT BRIDGE PRESETS — per vendor, how an old session is recognised.
+ *
+ * Shared by the Atlas API (which verifies the token and resolves the user) and
+ * the SDK middleware (which knows which cookie / header carries it), so both
+ * read one table. Pure data plus a few string templates: safe on every runtime.
+ *
+ * Three modes:
+ *   - `jwt`: the vendor's session (or a token inside it) is a JWT. Atlas
+ *     verifies it against the vendor's issuer and keys (JWKS, or an X.509 map
+ *     like Firebase session cookies use), maps `claims.subject` to the imported
+ *     user (`external_id` = the source user id), and spends `claims.sessionKey`
+ *     (`jti` / `sid`, falling back to the whole token) in the single-use ledger.
+ *   - `session_table`: an opaque token; Atlas looks up sha256(token) among the
+ *     sessions imported in the migration bundle.
+ *   - `remote`: the vendor's session can only be checked by asking the vendor
+ *     with the user's own token (Appwrite, PocketBase): Atlas calls
+ *     `remote.url` with the token filled into `{token}` and reads the subject
+ *     (and profile) from the JSON answer by dot path.
+ *
+ * Templates use `{var}` placeholders filled from the bridge settings'
+ * `preset_vars` (e.g. `{domain}`, `{region}`); {@link resolveMigrationBridgePreset}
+ * refuses a template with a missing variable.
+ *
+ * Vendor tracks register their preset (or refine the starter below) with
+ * {@link registerMigrationBridgePreset}; a test checks every preset resolves.
+ */
+export interface MigrationBridgeClaims {
+    /** Claim holding the source user id (default `sub`). */
+    subject: string;
+    email?: string;
+    emailVerified?: string;
+    name?: string;
+    /** Claim whose value spends the token in the single-use ledger (`jti`, `sid`); the whole token when absent. */
+    sessionKey?: string;
+    /**
+     * How the vendor says a second factor was passed: `amr:mfa` (the `amr` array
+     * contains `mfa`), `acr:<value>`, or `claim:<name>` (a truthy claim).
+     */
+    mfa?: string;
+}
+/**
+ * How the middleware gets the token out of the cookie: `raw` (the cookie value
+ * is the token), `supabase` (Supabase SSR's `base64-` JSON cookie, possibly
+ * chunked `.0`/`.1`, holding `access_token`), or a custom extractor a vendor
+ * track registers on the middleware side.
+ */
+export type TokenFormat = 'raw' | 'supabase' | (string & {});
+export interface MigrationBridgePreset {
+    id: string;
+    label: string;
+    mode: 'jwt' | 'session_table' | 'remote';
+    /** Variables the templates need, with a one-line hint each. */
+    vars?: Record<string, string>;
+    /** Optional variables and their defaults. */
+    defaults?: Record<string, string>;
+    jwt?: {
+        issuer: string;
+        /** Where the keys are. Omitted → OIDC discovery from the issuer. */
+        keysUrl?: string;
+        /** `jwks` (default) or `x509` (a `{ kid: PEM certificate }` map). */
+        keysFormat?: 'jwks' | 'x509';
+        /** Expected `aud` template(s); unchecked when absent. */
+        audience?: string[];
+        algorithms: string[];
+        claims: MigrationBridgeClaims;
+        /**
+         * Accept a validly signed token this many seconds past `exp` (each one still
+         * exchanges once). For vendors whose cookie holds a short-lived token that
+         * their client SDK refreshes and nothing refreshes after the switch. 0 by default.
+         */
+        expiredGraceSeconds?: number;
+        /** The vendor may sign with a shared secret (HS256) instead of keys (Supabase legacy JWT secret). */
+        allowSharedSecret?: boolean;
+        /**
+         * The token is not a JWT but another signed token Atlas checks natively:
+         * `magic_did` (Magic DID tokens — signed by the user's own key, subject the
+         * `iss` DID, audience the Magic client id). Default `jwt`.
+         */
+        tokenType?: 'jwt' | 'magic_did';
+    };
+    /**
+     * Mode `remote`: the vendor call that vouches for a token. Templates take the
+     * preset variables; `{token}` is the presented token and is filled only at
+     * call time, by the server.
+     */
+    remote?: MigrationBridgeRemote;
+    /**
+     * Cookies that may carry the token, most specific first. `*` matches any run
+     * of characters (Amplify names cookies per client id and username).
+     */
+    cookies: string[];
+    tokenFormat?: TokenFormat;
+    /** Read `Authorization: Bearer` too (API clients holding the old token). */
+    bearer?: boolean;
+    /** Cookies to clear once exchanged (defaults to `cookies`). */
+    clearCookies?: string[];
+    /**
+     * The cookie name collides with Atlas's own (`__session`): the middleware
+     * only treats it as the old vendor's when the token's `iss` is the vendor's.
+     */
+    sharesAtlasCookie?: boolean;
+    /** Integrator-facing notes (what must be configured at the vendor, caveats). */
+    notes?: string;
+}
+/** How a `remote` preset asks the vendor about a token. */
+export interface MigrationBridgeRemote {
+    /** URL template (`{var}` from the preset variables, `{token}` at call time). */
+    url: string;
+    method: 'GET' | 'POST';
+    /** Header templates, e.g. `{ authorization: 'Bearer {token}' }`. */
+    headers?: Record<string, string>;
+    /** Body template (POST). */
+    body?: string;
+    /** Dot path into the JSON answer holding the source user id (`record.id`, `$id`). */
+    subjectPath: string;
+    emailPath?: string;
+    emailVerifiedPath?: string;
+    namePath?: string;
+}
+export declare function registerMigrationBridgePreset(preset: MigrationBridgePreset, options?: {
+    replace?: boolean;
+}): void;
+export declare function getMigrationBridgePreset(id: string): MigrationBridgePreset | undefined;
+export declare function listMigrationBridgePresets(): MigrationBridgePreset[];
+/** The bridge settings a preset resolves to, every template filled in. */
+export interface ResolvedBridgePreset {
+    preset: string;
+    mode: 'jwt' | 'session_table' | 'remote';
+    issuer: string | null;
+    keysUrl: string | null;
+    keysFormat: 'jwks' | 'x509';
+    audience: string[] | null;
+    algorithms: string[];
+    claims: MigrationBridgeClaims;
+    expiredGraceSeconds: number;
+    cookies: string[];
+    tokenFormat: TokenFormat;
+    bearer: boolean;
+    clearCookies: string[];
+    sharesAtlasCookie: boolean;
+    /** Mode `remote`: the vendor call, preset variables filled, `{token}` left for the server. */
+    remote: MigrationBridgeRemote | null;
+}
+export declare class PresetVariableError extends Error {
+    readonly variable: string;
+    constructor(variable: string, message: string);
+}
+/**
+ * Fill a preset's templates. Throws {@link PresetVariableError} for a missing or
+ * malformed variable. Values are trimmed; a trailing slash on a URL-ish value
+ * is removed (`https://example.com/` → `https://example.com`).
+ */
+export declare function resolveMigrationBridgePreset(id: string, rawVars?: Record<string, string>): ResolvedBridgePreset;
+/** Does a cookie name match a preset pattern (`*` = any run of characters)? */
+export declare function cookieNameMatches(pattern: string, name: string): boolean;