@portaidentity/server 1.7.0

package/dist/lib/data-import.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Data import service.
+ *
+ * Imports configuration data from a JSON manifest with three modes:
+ * - merge: skip existing (match by slug), create new
+ * - overwrite: update existing, create new
+ * - dry-run: show what would change without applying
+ *
+ * All changes are applied in a single PostgreSQL transaction for atomicity.
+ * Entities are processed in 12 phases in dependency order:
+ * 1. Organizations (+branding, 2FA), 2. Applications, 3. Clients + secrets,
+ * 4. Roles, 5. Permissions, 6. Claim definitions, 7. Role-permission mappings,
+ * 8. Application modules, 9. Users, 10. User-role assignments,
+ * 11. User claim values, 12. System config overrides.
+ *
+ * Authentication material is never accepted. New users rely on the normal account-recovery
+ * boundary to establish credentials after provisioning.
+ *
+ * @module data-import
+ * @see 07-import-export-invitation.md
+ */
+import { z } from 'zod';
+/** Closed execution modes accepted by the import service. */
+export type ImportMode = 'merge' | 'overwrite' | 'dry-run';
+/** A single entity operation result */
+export interface ImportEntityResult {
+    /** Closed entity category. */
+    type: string;
+    /** Public natural-key component used to identify the entity. */
+    slug: string;
+    /** Human-readable entity label. */
+    name: string;
+    /** Mutable fields changed or planned by the operation. */
+    changes?: string[];
+    /** Indicates that a committed confidential-client create would issue a credential. */
+    credentialWillBeGenerated?: boolean;
+}
+/** A skipped entity with reason */
+export interface ImportSkippedResult {
+    /** Closed entity category. */
+    type: string;
+    /** Public natural-key component used to identify the entity. */
+    slug: string;
+    /** Stable explanation for the intentional no-op. */
+    reason: string;
+}
+/** An import error for a specific entity */
+export interface ImportErrorResult {
+    /** Closed entity category. */
+    type: string;
+    /** Public natural-key component used to identify the entity. */
+    slug: string;
+    /** Legacy internal diagnostic, never serialized by a successful import. */
+    error: string;
+}
+/** Client credentials generated during import (shown once, never stored in plaintext) */
+export interface ImportClientCredentials {
+    /** Public client display name. */
+    clientName: string;
+    /** Generated public client identifier, present only after commit. */
+    clientId?: string;
+    /** OIDC client category. */
+    clientType: 'confidential' | 'public';
+    /** Dry-run indication which never contains generated credential material. */
+    credentialWillBeGenerated?: boolean;
+    /** Raw secret — only present on create for confidential clients */
+    secretPlaintext?: string;
+    /** DB row ID of the generated secret */
+    secretId?: string;
+    /** Optional label for the generated secret. */
+    secretLabel?: string;
+    /** Optional expiry for the generated secret. */
+    secretExpiresAt?: string;
+}
+/** Full import result */
+export interface ImportResult {
+    /** Execution mode applied to the manifest. */
+    mode: ImportMode;
+    /** Entities created or planned for creation. */
+    created: ImportEntityResult[];
+    /** Entities updated or planned for update. */
+    updated: ImportEntityResult[];
+    /** Existing entities intentionally left unchanged. */
+    skipped: ImportSkippedResult[];
+    /** Present only on legacy rejected responses; successful imports omit error details. */
+    errors?: ImportErrorResult[];
+    /** Credentials generated by committed confidential-client creates. */
+    credentials: ImportClientCredentials[];
+}
+/** Closed public failure codes emitted by the import boundary. */
+export type ImportFailureCode = 'import_manifest_invalid' | 'import_plan_rejected' | 'import_execution_failed';
+/**
+ * Sanitized import failure which retains no manifest values or dependency diagnostics.
+ */
+export declare class ImportOperationError extends Error {
+    /** Stable public error discriminator. */
+    readonly code: ImportFailureCode;
+    /** Server-created identifier used to correlate private operational diagnostics. */
+    readonly correlationId: string;
+    /** Recommended public HTTP status. */
+    readonly status: 400 | 409 | 503;
+    /**
+     * Create a minimal import failure.
+     *
+     * @param code - Stable public failure category.
+     * @param status - Recommended HTTP status for the route boundary.
+     * @param correlationId - Optional existing server correlation identifier.
+     */
+    constructor(code: ImportFailureCode, status: 400 | 409 | 503, correlationId?: string);
+}
+/**
+ * Schema for role-permission mappings.
+ * Links roles to permissions after both are created during import.
+ * Uses slug-based references resolved against the appMap.
+ */
+declare const rolePermissionMappingSchema: z.ZodObject<{
+    role_slug: z.ZodString;
+    permission_slugs: z.ZodArray<z.ZodString>;
+    application_slug: z.ZodString;
+    organization_slug: z.ZodString;
+}, z.core.$strict>;
+export type RolePermissionMappingInput = z.infer<typeof rolePermissionMappingSchema>;
+/** The full import manifest schema */
+export declare const importManifestSchema: z.ZodObject<{
+    version: z.ZodLiteral<"1.0">;
+    exportedAt: z.ZodOptional<z.ZodString>;
+    organizations: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        slug: z.ZodString;
+        default_login_methods: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            magic_link: "magic_link";
+            password: "password";
+        }>>>;
+        default_locale: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        two_factor_policy: z.ZodOptional<z.ZodEnum<{
+            optional: "optional";
+            required_any: "required_any";
+            required_email: "required_email";
+            required_totp: "required_totp";
+        }>>;
+        branding_primary_color: z.ZodOptional<z.ZodString>;
+        branding_company_name: z.ZodOptional<z.ZodString>;
+        branding_custom_css: z.ZodOptional<z.ZodString>;
+        branding_logo_url: z.ZodOptional<z.ZodString>;
+        branding_favicon_url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>>;
+    applications: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        slug: z.ZodString;
+        organization_slug: z.ZodString;
+        description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strict>>>>;
+    clients: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        client_name: z.ZodString;
+        application_slug: z.ZodString;
+        organization_slug: z.ZodString;
+        client_type: z.ZodEnum<{
+            confidential: "confidential";
+            public: "public";
+        }>;
+        application_type: z.ZodOptional<z.ZodEnum<{
+            native: "native";
+            spa: "spa";
+            web: "web";
+        }>>;
+        grant_types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            authorization_code: "authorization_code";
+            client_credentials: "client_credentials";
+            refresh_token: "refresh_token";
+        }>>>;
+        redirect_uris: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        response_types: z.ZodOptional<z.ZodArray<z.ZodLiteral<"code">>>;
+        scope: z.ZodOptional<z.ZodString>;
+        login_methods: z.ZodNullable<z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            magic_link: "magic_link";
+            password: "password";
+        }>>>>;
+        token_endpoint_auth_method: z.ZodOptional<z.ZodEnum<{
+            client_secret_basic: "client_secret_basic";
+            client_secret_post: "client_secret_post";
+            none: "none";
+        }>>;
+        post_logout_redirect_uris: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allowed_origins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        require_pkce: z.ZodOptional<z.ZodBoolean>;
+        secret_label: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        secret_expires_at: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strict>>>>;
+    roles: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        slug: z.ZodString;
+        application_slug: z.ZodString;
+        organization_slug: z.ZodString;
+        description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strict>>>>;
+    permissions: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        slug: z.ZodString;
+        application_slug: z.ZodString;
+        organization_slug: z.ZodString;
+        description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strict>>>>;
+    claim_definitions: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        slug: z.ZodString;
+        application_slug: z.ZodString;
+        organization_slug: z.ZodString;
+        claim_type: z.ZodEnum<{
+            boolean: "boolean";
+            json: "json";
+            number: "number";
+            string: "string";
+        }>;
+        description: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strict>>>>;
+    role_permission_mappings: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        role_slug: z.ZodString;
+        permission_slugs: z.ZodArray<z.ZodString>;
+        application_slug: z.ZodString;
+        organization_slug: z.ZodString;
+    }, z.core.$strict>>>>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    users: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        email: z.ZodString;
+        organization_slug: z.ZodString;
+        given_name: z.ZodOptional<z.ZodString>;
+        family_name: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodEnum<{
+            active: "active";
+            inactive: "inactive";
+        }>>;
+        email_verified: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>>;
+    application_modules: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        slug: z.ZodString;
+        application_slug: z.ZodString;
+        organization_slug: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodEnum<{
+            active: "active";
+            inactive: "inactive";
+        }>>;
+    }, z.core.$strict>>>>;
+    user_role_assignments: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        email: z.ZodString;
+        organization_slug: z.ZodString;
+        application_slug: z.ZodString;
+        role_slug: z.ZodString;
+    }, z.core.$strict>>>>;
+    user_claim_values: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        email: z.ZodString;
+        organization_slug: z.ZodString;
+        application_slug: z.ZodString;
+        claim_slug: z.ZodString;
+        value: z.ZodUnknown;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>;
+/** Strictly parsed version 1.0 import manifest. */
+export type ImportManifest = z.infer<typeof importManifestSchema>;
+/**
+ * Import configuration from a JSON manifest.
+ *
+ * Processes entities in dependency order within a single transaction:
+ * organizations → applications → clients → roles → permissions → claims.
+ *
+ * @param manifest - The validated import manifest
+ * @param mode - Import mode: merge, overwrite, or dry-run
+ * @param actorId - ID of the admin performing the import (for audit log)
+ * @returns Import result with created/updated/skipped/error counts
+ * @throws Error if manifest version is incompatible
+ */
+export declare function importData(manifestInput: ImportManifest, mode: ImportMode, actorId?: string, organizationId?: string): Promise<ImportResult>;
+export {};
+//# sourceMappingURL=data-import.d.ts.map

package/dist/lib/data-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-import.d.ts","sourceRoot":"","sources":["../../src/lib/data-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAqBxB,6DAA6D;AAC7D,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,CAAC;AAE3D,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,sFAAsF;IACtF,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,mCAAmC;AACnC,MAAM,WAAW,mBAAmB;IAClC,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;CACf;AAED,yFAAyF;AACzF,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,UAAU,EAAE,cAAc,GAAG,QAAQ,CAAC;IACtC,6EAA6E;IAC7E,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,yBAAyB;AACzB,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,IAAI,EAAE,UAAU,CAAC;IACjB,gDAAgD;IAChD,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,8CAA8C;IAC9C,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,sDAAsD;IACtD,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,wFAAwF;IACxF,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC7B,sEAAsE;IACtE,WAAW,EAAE,uBAAuB,EAAE,CAAC;CACxC;AAED,kEAAkE;AAClE,MAAM,MAAM,iBAAiB,GAC3B,yBAAyB,GAAG,sBAAsB,GAAG,yBAAyB,CAAC;AAEjF;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,yCAAyC;IACzC,SAAgB,IAAI,EAAE,iBAAiB,CAAC;IAExC,mFAAmF;IACnF,SAAgB,aAAa,EAAE,MAAM,CAAC;IAEtC,sCAAsC;IACtC,SAAgB,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAExC;;;;;;OAMG;IACH,YAAmB,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,aAAa,CAAC,EAAE,MAAM,EAM1F;CACF;AAyJD;;;;GAIG;AACH,QAAA,MAAM,2BAA2B;;;;;kBAOtB,CAAC;AAEZ,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AA2ErF,sCAAsC;AACtC,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAmG7B,CAAC;AAEL,mDAAmD;AACnD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAMlE;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAC9B,aAAa,EAAE,cAAc,EAC7B,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,MAAM,EAChB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,YAAY,CAAC,CAgPvB"}