@atlasauth/backend 0.23.0 → 0.24.0

package/dist/client/migrations.d.ts

@@ -0,0 +1,286 @@
+import { type BetterAuthImportActionItem } from './better-auth-imports';
+import { type RequestFn } from './request';
+import type { CursorPage, CursorParams } from './types';
+/**
+ * Migrate to Atlas from any source: the vendor-neutral surface every vendor
+ * plugs into (`{source}`: `auth0`, `clerk`, `cognito`, `firebase`, …,
+ * `better_auth`, `custom`).
+ *
+ *   imports  `/v1/migrations/{source}/imports` — a sealed migration bundle
+ *            (`@atlasauth/migrate`, or `atlas migrate export <vendor>`):
+ *            `getPublicKey()`, `upload()` (create + parts + finalize), read the
+ *            `report`, `apply()`; applying again after a failure resumes.
+ *   bridge   `/v1/migrations/{source}/bridge` — the zero-logout bridge settings
+ *            (a vendor JWT preset, or imported sessions).
+ *   sources  `/v1/migrations/sources` — what each source supports.
+ */
+export type MigrationSourceId = 'better_auth' | 'auth0' | 'clerk' | 'cognito' | 'firebase' | 'supabase' | 'workos' | 'authjs' | 'okta' | 'stytch' | 'keycloak' | 'fusionauth' | 'kinde' | 'descope' | 'lucia' | 'ory' | 'frontegg' | 'custom';
+export type MigrationImportStatus = 'uploading' | 'analyzing' | 'ready' | 'invalid' | 'queued' | 'applying' | 'completed' | 'failed';
+export interface MigrationImportKey {
+    object: 'migration_import_key';
+    kid: string;
+    /** base64url raw X25519 public key. One key serves every source. */
+    public_key: string;
+    alg: 'X25519-HKDF-SHA256-A256GCM';
+    status: 'active' | 'retired';
+    fingerprint: string;
+    /** `kid:public_key`, the form the exporters take. */
+    compact: string;
+    created_at: number;
+    retired_at: number | null;
+}
+/** Options of a non-Better-Auth import (a `better_auth` import takes {@link BetterAuthImportOptions}). */
+export interface MigrationImportOptions {
+    models?: Array<'organization' | 'role' | 'user' | 'identity' | 'mfa_factor' | 'passkey' | 'membership' | 'invitation' | 'api_key' | 'sso_connection' | 'jwks' | 'session'>;
+    on_email_conflict?: 'skip' | 'link';
+    create_app_roles?: boolean;
+    import_oauth_tokens?: boolean;
+    passkeys_on_rp_mismatch?: 'skip' | 'import';
+    import_sessions?: boolean;
+    import_jwks?: boolean;
+    jwks_cutover_days?: number;
+    /** Source provider name → Atlas provider key. */
+    provider_map?: Record<string, string>;
+    /** Hash parameters that live outside the export, per algorithm id (Firebase signer key …). */
+    password_hash_params?: Record<string, Record<string, string | number | boolean>>;
+    retain_bundle?: boolean;
+    [option: string]: unknown;
+}
+interface MigrationReportCommon {
+    skipped: Array<{
+        model: string;
+        row_id: string | null;
+        reason_code: string;
+        reason: string;
+    }>;
+    skipped_total: number;
+    skipped_by_code: Record<string, number>;
+    conflicts: Array<{
+        model: string;
+        row_id: string | null;
+        code: string;
+        message: string;
+        resolution: 'merge' | 'skip';
+        existing_id: string | null;
+    }>;
+    conflicts_total: number;
+    action_items: BetterAuthImportActionItem[];
+    warnings: string[];
+    notes: Record<string, unknown>;
+}
+export interface MigrationImportReport extends MigrationReportCommon {
+    models: Array<{
+        model: string;
+        label: string;
+        found: number;
+        will_create: number;
+        will_update: number;
+        will_skip: number;
+    }>;
+    /** Users per password-hash algorithm. */
+    password_algorithms?: Record<string, number>;
+}
+export interface MigrationImportResult extends MigrationReportCommon {
+    models: Array<{
+        model: string;
+        label: string;
+        found: number;
+        created: number;
+        updated: number;
+        unchanged: number;
+        skipped: number;
+        failed: number;
+    }>;
+    completed_at: number | null;
+}
+export interface MigrationImport {
+    object: 'migration_import';
+    id: string;
+    source: MigrationSourceId;
+    format: 'atlas-migration-bundle' | 'atlas-better-auth-bundle';
+    status: MigrationImportStatus;
+    key_id: string | null;
+    parts: number;
+    bytes: number;
+    bundle_sha256: string | null;
+    bundle_purged: boolean;
+    options: Record<string, unknown>;
+    manifest: {
+        exported_at: string;
+        exporter: {
+            name: string;
+            version: string;
+        };
+        origin: string | null;
+        source_version: string | null;
+        models: string[];
+        providers: string[];
+        rp_id: string | null;
+        warnings: string[];
+    } | null;
+    total: number;
+    progress: {
+        total: number;
+        processed: number;
+        succeeded: number;
+        failed: number;
+        percent: number;
+    } | null;
+    report: MigrationImportReport | null;
+    result: MigrationImportResult | null;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    created_at: number;
+    updated_at: number;
+    analyzed_at: number | null;
+    apply_started_at: number | null;
+    completed_at: number | null;
+}
+export interface MigrationClaimMap {
+    subject?: string;
+    email?: string;
+    email_verified?: string;
+    name?: string;
+    session_key?: string;
+    mfa?: string;
+}
+/** PUT body of the bridge settings; every field optional, merged onto the stored ones. */
+export interface MigrationBridgeSettingsUpdate {
+    enabled?: boolean;
+    ends_at?: string | number | null;
+    mode?: 'jwt' | 'session_table' | 'remote';
+    preset?: string | null;
+    preset_vars?: Record<string, string>;
+    issuer?: string | null;
+    jwks_url?: string | null;
+    audience?: string[] | null;
+    algorithms?: string[] | null;
+    claim_map?: MigrationClaimMap;
+    expired_grace_seconds?: number;
+    cookie_names?: string[];
+    create_users?: boolean;
+    /** Write-only HS256 secret; omit to keep, null to clear. */
+    shared_secret?: string | null;
+}
+export interface MigrationBridgeSettings {
+    object: 'migration_bridge';
+    source: MigrationSourceId;
+    enabled: boolean;
+    ends_at: number | null;
+    mode: 'jwt' | 'session_table' | 'remote';
+    preset: string | null;
+    preset_vars: Record<string, string>;
+    issuer: string | null;
+    jwks_url: string | null;
+    audience: string[] | null;
+    algorithms: string[];
+    claim_map: Record<string, string>;
+    expired_grace_seconds: number;
+    cookie_names: string[];
+    create_users: boolean;
+    has_shared_secret: boolean;
+    exchange_path: string;
+    stats: {
+        exchanged: number;
+        from_import: number;
+        from_jwt: number;
+    };
+    created_at: number | null;
+    updated_at: number | null;
+}
+export interface MigrationSourceView {
+    object: 'migration_source';
+    source: MigrationSourceId;
+    label: string;
+    models: string[];
+    passwords: 'export' | 'ticket' | 'lazy' | 'none';
+    export_via: Array<'api' | 'file' | 'database' | 'support_ticket'>;
+    bridge: {
+        mode: 'jwt' | 'session_table' | 'remote' | 'none';
+        preset: string | null;
+        vars: Record<string, string>;
+        cookies: string[];
+    };
+    lazy_migration: {
+        preset: string;
+        config: Record<string, {
+            label: string;
+            required: boolean;
+        }>;
+        secret: {
+            label: string;
+            required: boolean;
+        } | null;
+    } | null;
+    password_algorithms: string[];
+    limits: string | null;
+}
+export declare function migrationsResource(request: RequestFn): {
+    /** Every migration source and what it supports. */
+    sources(): Promise<CursorPage<MigrationSourceView>>;
+    /** The import surface of one source: `migrations.imports('auth0').upload(text)`. */
+    imports: (source: MigrationSourceId | string) => {
+        /** The import public key (created on first read; shared by every source). */
+        getPublicKey(): Promise<MigrationImportKey>;
+        /** Replace the import key; bundles sealed to the old one no longer finalize. */
+        rotatePublicKey(): Promise<MigrationImportKey>;
+        create(body?: {
+            options?: MigrationImportOptions;
+        }, idempotencyKey?: string): Promise<MigrationImport>;
+        list(params?: CursorParams): Promise<CursorPage<MigrationImport>>;
+        get(id: string): Promise<MigrationImport>;
+        /** Upload part `part` (1-based) of the sealed bundle text. */
+        uploadPart(id: string, part: number, data: string): Promise<{
+            object: "migration_import_part";
+            import_id: string;
+            part: number;
+            bytes: number;
+            sha256: string;
+        }>;
+        /** Close the upload; Atlas checks the key and the format, then runs the dry run. */
+        finalize(id: string): Promise<MigrationImport>;
+        dryRun(id: string, body?: {
+            options?: MigrationImportOptions;
+        }): Promise<MigrationImport>;
+        /** Import (or resume). Pass confirm_conflicts when the dry run reported conflicts. */
+        apply(id: string, body?: {
+            confirm_conflicts?: boolean;
+        }): Promise<MigrationImport>;
+        delete(id: string): Promise<{
+            object: "migration_import";
+            id: string;
+            deleted: true;
+        }>;
+        /**
+         * Create an import (or continue `importId`), upload the sealed bundle text
+         * in parts from `resumeFrom` (1-based) and finalize it.
+         */
+        upload(bundleText: string, opts?: {
+            options?: MigrationImportOptions;
+            partBytes?: number;
+            importId?: string;
+            resumeFrom?: number;
+            onPart?: (n: number, of: number) => void;
+        }): Promise<MigrationImport>;
+        /** Poll until the import leaves analyzing / queued / applying. */
+        waitFor(id: string, opts?: {
+            intervalMs?: number;
+            timeoutMs?: number;
+            onProgress?: (imp: MigrationImport) => void;
+            sleep?: (ms: number) => Promise<void>;
+        }): Promise<MigrationImport>;
+    };
+    /** The zero-logout bridge settings of one source. */
+    bridge: (source: MigrationSourceId | string) => {
+        get(): Promise<MigrationBridgeSettings>;
+        update(body: MigrationBridgeSettingsUpdate): Promise<MigrationBridgeSettings>;
+        delete(): Promise<{
+            object: "migration_bridge";
+            source: string;
+            deleted: true;
+        }>;
+    };
+};
+export {};

package/dist/client/migrations.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrationsResource = migrationsResource;
+const better_auth_imports_1 = require("./better-auth-imports");
+const request_1 = require("./request");
+const TERMINAL = ['ready', 'invalid', 'completed', 'failed'];
+function migrationsResource(request) {
+    const importsFor = (source) => {
+        const base = `/v1/migrations/${(0, request_1.enc)(source)}/imports`;
+        const self = {
+            /** The import public key (created on first read; shared by every source). */
+            getPublicKey() {
+                return request({ method: 'GET', path: `${base}/public_key` });
+            },
+            /** Replace the import key; bundles sealed to the old one no longer finalize. */
+            rotatePublicKey() {
+                return request({ method: 'POST', path: `${base}/public_key/rotate` });
+            },
+            create(body = {}, idempotencyKey) {
+                return request({ method: 'POST', path: base, body, idempotencyKey });
+            },
+            list(params = {}) {
+                return request({ method: 'GET', path: base, query: { ...params } });
+            },
+            get(id) {
+                return request({ method: 'GET', path: `${base}/${(0, request_1.enc)(id)}` });
+            },
+            /** Upload part `part` (1-based) of the sealed bundle text. */
+            uploadPart(id, part, data) {
+                return request({ method: 'PUT', path: `${base}/${(0, request_1.enc)(id)}/parts/${part}`, body: { data } });
+            },
+            /** Close the upload; Atlas checks the key and the format, then runs the dry run. */
+            finalize(id) {
+                return request({ method: 'POST', path: `${base}/${(0, request_1.enc)(id)}/finalize` });
+            },
+            dryRun(id, body = {}) {
+                return request({ method: 'POST', path: `${base}/${(0, request_1.enc)(id)}/dry_run`, body });
+            },
+            /** Import (or resume). Pass confirm_conflicts when the dry run reported conflicts. */
+            apply(id, body = {}) {
+                return request({ method: 'POST', path: `${base}/${(0, request_1.enc)(id)}/apply`, body });
+            },
+            delete(id) {
+                return request({ method: 'DELETE', path: `${base}/${(0, request_1.enc)(id)}` });
+            },
+            /**
+             * Create an import (or continue `importId`), upload the sealed bundle text
+             * in parts from `resumeFrom` (1-based) and finalize it.
+             */
+            async upload(bundleText, opts = {}) {
+                const parts = (0, better_auth_imports_1.splitBundleParts)(bundleText, opts.partBytes);
+                if (parts.length === 0)
+                    throw new Error('The bundle is empty.');
+                const id = opts.importId ?? (await self.create(opts.options ? { options: opts.options } : {})).id;
+                for (let i = Math.max(0, (opts.resumeFrom ?? 1) - 1); i < parts.length; i++) {
+                    await self.uploadPart(id, i + 1, parts[i]);
+                    opts.onPart?.(i + 1, parts.length);
+                }
+                return self.finalize(id);
+            },
+            /** Poll until the import leaves analyzing / queued / applying. */
+            async waitFor(id, opts = {}) {
+                const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+                const deadline = Date.now() + (opts.timeoutMs ?? 6 * 3600_000);
+                for (;;) {
+                    const imp = await self.get(id);
+                    opts.onProgress?.(imp);
+                    if (TERMINAL.includes(imp.status) || imp.status === 'uploading')
+                        return imp;
+                    if (Date.now() > deadline)
+                        throw new Error(`Timed out waiting for migration import ${id} (status ${imp.status}).`);
+                    await sleep(opts.intervalMs ?? 2000);
+                }
+            },
+        };
+        return self;
+    };
+    const bridgeFor = (source) => {
+        const path = `/v1/migrations/${(0, request_1.enc)(source)}/bridge`;
+        return {
+            get() {
+                return request({ method: 'GET', path });
+            },
+            update(body) {
+                return request({ method: 'PUT', path, body });
+            },
+            delete() {
+                return request({ method: 'DELETE', path });
+            },
+        };
+    };
+    return {
+        /** Every migration source and what it supports. */
+        sources() {
+            return request({ method: 'GET', path: '/v1/migrations/sources' });
+        },
+        /** The import surface of one source: `migrations.imports('auth0').upload(text)`. */
+        imports: importsFor,
+        /** The zero-logout bridge settings of one source. */
+        bridge: bridgeFor,
+    };
+}
+//# sourceMappingURL=migrations.js.map

package/dist/client/migrations.js.map

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

package/dist/framework-bridge.d.ts

@@ -0,0 +1,98 @@
+import type { MigrationTokenExtractor } from './migration-bridge';
+/**
+ * Zero-logout bridge for the SELF-HOSTED frameworks (Auth.js, Lucia,
+ * Passport, iron-session, Devise, Django): their presets, and the token
+ * extractors `migrationBridge({ extractToken })` takes.
+ *
+ * Two families:
+ *
+ *   - Database sessions (Auth.js database strategy, Lucia, express-session
+ *     stores, Django's database backend, Rails' activerecord-session_store):
+ *     preset mode `session_table`. The cookie carries an opaque id; Atlas finds
+ *     sha256(id) among the sessions you imported. Lucia, Auth.js and Django
+ *     cookies are read as they are; express-session's cookie is signed
+ *     (`s:<id>.<signature>`), so {@link expressSessionExtractor} pulls the id out.
+ *
+ *   - Sealed cookies (Auth.js JWT strategy, iron-session, Rails' cookie store
+ *     under Devise, Django's signed-cookie backend): there is no session row to
+ *     import — the cookie IS the session, and only your app's secret opens it.
+ *     The extractor opens it ON YOUR SERVER and hands Atlas a short-lived
+ *     BRIDGE ASSERTION instead: an HS256 JWT (`iss` = `urn:atlas:bridge:<source>`,
+ *     `sub` = the user id you exported, `jti` = the old session's id) signed
+ *     with a bridge secret you generate and store in the bridge settings
+ *     (`shared_secret`). Your AUTH_SECRET / secret_key_base / SECRET_KEY /
+ *     iron password never leave your server; Atlas verifies the assertion,
+ *     spends its `jti` once, and signs the user in.
+ */
+/** The issuer of a bridge assertion for a source. */
+export declare function bridgeAssertionIssuer(source: string): string;
+/** Lifetime of a bridge assertion: it is exchanged immediately, once. */
+export declare const BRIDGE_ASSERTION_TTL_SECONDS = 120;
+export interface BridgeAssertion {
+    source: string;
+    /** The source user id (the `user.id` your export wrote). */
+    sub: string;
+    /** The old session's own id, so the session exchanges once (single-use ledger). */
+    sessionKey: string;
+    email?: string | null;
+    name?: string | null;
+    /** The old session had already passed a second factor. */
+    mfa?: boolean;
+}
+/** Sign a bridge assertion with the bridge secret (HS256). */
+export declare function signBridgeAssertion(assertion: BridgeAssertion, bridgeSecret: string, now?: Date): Promise<string>;
+/**
+ * Auth.js / NextAuth, either session strategy. A database-session cookie is
+ * returned as it is (preset `authjs`); a JWT-strategy cookie is decrypted with
+ * `secret` (AUTH_SECRET / NEXTAUTH_SECRET, or the rotation list) and turned
+ * into a bridge assertion (preset `authjs_jwt`, needs `bridgeSecret`).
+ */
+export declare function authJsExtractor(options: {
+    secret?: string | readonly string[];
+    bridgeSecret?: string;
+    cookieName?: string;
+}): MigrationTokenExtractor;
+/**
+ * Passport / express-session: the session id out of the signed `connect.sid`
+ * cookie (preset `passport`). Pass `secrets` (your `session({ secret })`) to
+ * check the signature as express-session does.
+ */
+export declare function expressSessionExtractor(options?: {
+    cookieName?: string;
+    secrets?: string | readonly string[];
+}): MigrationTokenExtractor;
+/**
+ * iron-session: unseal the cookie with your session password and assert the
+ * user at `userIdPath` (default: `userId`, then `user.id`, then `id`).
+ */
+export declare function ironSessionExtractor(options: {
+    cookieName: string;
+    password: string | Readonly<Record<string, string>>;
+    bridgeSecret: string;
+    userIdPath?: string;
+    emailPath?: string;
+}): MigrationTokenExtractor;
+/**
+ * Devise on Rails' cookie store: decrypt `_<app>_session` with
+ * `secret_key_base` and assert the Warden user (`scope`, default `user`).
+ */
+export declare function deviseExtractor(options: {
+    cookieName: string;
+    secretKeyBase: string | readonly string[];
+    bridgeSecret: string;
+    scope?: string;
+    keyDigest?: 'SHA-256' | 'SHA-1';
+}): MigrationTokenExtractor;
+/**
+ * Django's signed-cookie session backend: verify the cookie with SECRET_KEY
+ * (then SECRET_KEY_FALLBACKS) and assert `_auth_user_id`.
+ */
+export declare function djangoSignedCookieExtractor(options: {
+    secretKey: string | readonly string[];
+    bridgeSecret: string;
+    cookieName?: string;
+    /** SESSION_COOKIE_AGE (default two weeks). */
+    maxAgeSeconds?: number;
+}): MigrationTokenExtractor;
+/** The preset ids this module registers (for docs and the settings UI). */
+export declare const FRAMEWORK_BRIDGE_PRESETS: string[];