@atlasauth/cli 0.11.0 → 0.13.0

package/dist/migrate/export/logto.d.ts

@@ -0,0 +1,150 @@
+import type { PasswordHash, UserRecord } from '@atlasauth/migrate';
+import { type Row, type Tables } from './frameworks/tables';
+import { RecordSet, type Obj } from './record-set';
+import { VendorHttp } from './vendor-http';
+/**
+ * `atlas migrate export logto` — Logto (self-hosted OSS and Logto Cloud) onto
+ * the canonical bundle models. Two ways in:
+ *
+ *   - a DATABASE DUMP of a self-hosted Logto (one file per table, made with
+ *     `psql \copy … csv header` or `json_agg`, see the guide): everything,
+ *     including MFA secrets — TOTP keys, WebAuthn credentials (passkeys) and
+ *     backup codes live in `users.mfa_verifications`, which no API returns;
+ *   - the MANAGEMENT API with a machine-to-machine app (`client_credentials`
+ *     against `{endpoint}/oidc/token`, resource `https://{tenant}.logto.app/api`,
+ *     `default` for OSS): users, roles, organizations, invitations, SSO
+ *     connectors. The API is asked for password hashes too
+ *     (`includePasswordHash=true`) and uses them when a Logto version returns
+ *     them; otherwise passwords move by lazy migration. MFA secrets never
+ *     leave over the API: those users enrol again.
+ *
+ * What maps where:
+ *   - users: username, primary email / phone (Logto only stores them once
+ *     verified, or set by an admin), name, avatar, OIDC profile, custom data;
+ *     suspended users arrive banned. `user.id` is the Logto user id, the `sub`
+ *     of every Logto token.
+ *   - passwords: Argon2i/id/d PHC strings, bcrypt, unsalted MD5/SHA1/SHA256
+ *     hex, and `Legacy` expressions (`["sha256", ["salt", "@"], "…"]`): the
+ *     plain shapes map onto the registry's ids, the rest keep the expression
+ *     for the `logto_legacy` verifier.
+ *   - social identities (`users.identities`, keyed by connector target) and
+ *     enterprise SSO identities (`user_sso_identities`, with their connector);
+ *   - roles (tenant "User" roles with their API scopes as permissions; M2M
+ *     roles are app credentials and stay behind), organizations (JIT email
+ *     domains as verified domains), organization roles with organization and
+ *     API scopes, memberships, invitations;
+ *   - personal access tokens (stored in plain text by Logto: Atlas keeps the
+ *     sha256, so they keep working);
+ *   - the tenant's public signing keys (`/oidc/jwks`) for the cutover.
+ */
+export interface LogtoExportOptions {
+    /** A self-hosted Logto database dump (one table per file). */
+    tables?: Tables;
+    /** The Logto endpoint (`https://auth.example.com`, `https://abc123.logto.app`): the Management API, the JWKS, the passkey rp id and SAML SP URLs. */
+    endpoint?: string;
+    /** A machine-to-machine app with the Management API role (API export). */
+    m2m?: {
+        appId: string;
+        appSecret: string;
+    };
+    /** The tenant: `default` on a self-hosted Logto, the Cloud tenant id (the `abc123` of abc123.logto.app). */
+    tenantId?: string;
+    /** The WebAuthn relying-party id passkeys were registered on (default: the endpoint's host). */
+    rpId?: string;
+    /** API export: read each user's personal access tokens too (one call per user). */
+    personalAccessTokens?: boolean;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    onProgress?: (message: string) => void;
+}
+/** Everything the record mapping needs, the same shape from a dump or the API (camelCase rows). */
+export interface LogtoSnapshot {
+    source: 'database' | 'api';
+    users: Obj[];
+    /** Tenant roles of type User (machine-to-machine roles are left out). */
+    roles: Obj[];
+    /** Role id → permission (scope) names. */
+    rolePermissions: Map<string, string[]>;
+    /** User id → role ids. */
+    userRoles: Map<string, string[]>;
+    organizations: Obj[];
+    organizationRoles: Obj[];
+    /** Organization role id → organization scope and API scope names. */
+    organizationRolePermissions: Map<string, string[]>;
+    members: Array<{
+        organizationId: string;
+        userId: string;
+        roleIds: string[];
+    }>;
+    invitations: Array<{
+        row: Obj;
+        roleIds: string[];
+    }>;
+    /** Organization id → JIT email domains. */
+    organizationDomains: Map<string, string[]>;
+    ssoConnectors: Obj[];
+    ssoIdentities: Obj[];
+    personalAccessTokens: Obj[];
+    jwks: Obj[];
+    /** Users carry `mfaVerifications` (a database dump); the API never returns factor secrets. */
+    hasFactors: boolean;
+}
+export declare function exportLogto(opts: LogtoExportOptions): Promise<RecordSet>;
+/** `https://auth.example.com/` → `https://auth.example.com` (https only, no path). */
+export declare function normalizeEndpoint(raw: string): string;
+/** The Cloud tenant id of `https://abc123.logto.app`, or null for any other host. */
+export declare function tenantOfEndpoint(endpoint: string): string | null;
+/** The Management API resource indicator of a tenant. */
+export declare function managementResource(tenantId: string): string;
+/** A database row as the Management API would spell it: camelCase keys, JSONB parsed. */
+export declare function logtoRow(row: Row): Obj;
+/** One table's rows of one tenant (a dump made with `where tenant_id = …` has every row already). */
+export declare function tenantRows(tables: Tables, name: string, tenantId: string): Obj[];
+export declare function snapshotFromTables(tables: Tables, tenantId: string): LogtoSnapshot;
+/** A Management API client: an M2M access token fetched (and refreshed) on this machine. */
+export declare function logtoManagementHttp(o: {
+    endpoint: string;
+    m2m: {
+        appId: string;
+        appSecret: string;
+    };
+    tenantId: string;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}): VendorHttp;
+export declare function fetchLogtoSnapshot(o: Omit<LogtoExportOptions, 'tables' | 'endpoint' | 'm2m'> & {
+    endpoint: string;
+    m2m: {
+        appId: string;
+        appSecret: string;
+    };
+    tenantId: string;
+    onProgress: (m: string) => void;
+    warnings?: string[];
+}): Promise<LogtoSnapshot & {
+    warnings: string[];
+}>;
+/** A Logto `Legacy` expression `["algorithm", [args with "@"], "hash"]`, or null. */
+export declare function parseLegacyExpression(value: string): {
+    algorithm: string;
+    args: string[];
+    hash: string;
+} | null;
+/**
+ * A Logto password digest and its `password_encryption_method` → the bundle's
+ * password. Null when the user has none or Logto itself could not verify it.
+ */
+export declare function mapLogtoPassword(digest: unknown, method: unknown): PasswordHash | null;
+/** One Logto user → a user record (null when it has nothing to sign in with). */
+export declare function mapLogtoUser(u: Obj, roles?: string[]): {
+    user: UserRecord | null;
+    passwordUnsupported: boolean;
+};
+export declare function buildLogtoRecordSet(snap: LogtoSnapshot & {
+    warnings?: string[];
+}, o: {
+    endpoint?: string;
+    tenantId: string;
+    rpId?: string;
+}): RecordSet;