@portaidentity/server 1.7.0

package/dist/auth/recovery-job-repository.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Durable PostgreSQL repository for account-recovery work.
+ *
+ * Public request handlers enqueue only protected, tenant-bound input. A worker later claims a
+ * bounded batch and performs account-specific work outside the request path. Every transition is
+ * conditional on the current claim owner so a stale worker cannot complete or reschedule work
+ * reclaimed by another process.
+ */
+import type { Pool, PoolClient, QueryResult, QueryResultRow } from 'pg';
+/** Closed recovery operations accepted by the durable queue. */
+export declare const RECOVERY_JOB_TYPES: readonly ['magic_link', 'password_reset'];
+/** Closed durable lifecycle states for recovery work. */
+export declare const RECOVERY_JOB_STATUSES: readonly ['available', 'claimed', 'completed', 'terminal_failure'];
+/** Maximum number of jobs one worker pass may claim. */
+export declare const RECOVERY_JOB_CLAIM_LIMIT = 25;
+/** Maximum processing attempts retained by the durable schema. */
+export declare const RECOVERY_JOB_ATTEMPT_LIMIT = 5;
+/** Recovery operation represented by a durable job. */
+export type RecoveryJobType = (typeof RECOVERY_JOB_TYPES)[number];
+/** Durable lifecycle state of recovery work. */
+export type RecoveryJobStatus = (typeof RECOVERY_JOB_STATUSES)[number];
+/**
+ * Authenticated-encryption envelope for a normalized recovery address.
+ *
+ * The repository treats these values as opaque protected bytes encoded by the caller. Plaintext
+ * addresses must never cross this boundary.
+ */
+export interface ProtectedRecoveryAddress {
+    /** Authenticated ciphertext encoded as base64url. */
+    readonly ciphertext: string;
+    /** Unique AES-GCM initialization vector encoded as base64url. */
+    readonly iv: string;
+    /** AES-GCM authentication tag encoded as base64url. */
+    readonly tag: string;
+    /** Non-secret identifier for the encryption key used by the envelope. */
+    readonly keyId: string;
+}
+/** Input accepted when one public recovery request enqueues durable work. */
+export interface EnqueueRecoveryJobInput {
+    /** Recovery operation to perform. */
+    readonly jobType: RecoveryJobType;
+    /** Tenant authority resolved by the public route. */
+    readonly organizationId: string;
+    /** Protected normalized recovery address. */
+    readonly protectedAddress: ProtectedRecoveryAddress;
+    /** OIDC interaction binding for a magic-link request, otherwise null. */
+    readonly interactionUid: string | null;
+    /** Keyed, domain-separated digest identifying this admitted request. */
+    readonly idempotencyDigest: string;
+    /** Earliest time at which a worker may claim the job. */
+    readonly availableAt: Date;
+}
+/** Durable recovery job returned to request and worker services. */
+export interface RecoveryJob {
+    /** Durable job identifier. */
+    readonly id: string;
+    /** Recovery operation represented by the job. */
+    readonly jobType: RecoveryJobType;
+    /** Tenant authority persisted with the job. */
+    readonly organizationId: string;
+    /** Protected recovery address. */
+    readonly protectedAddress: ProtectedRecoveryAddress;
+    /** OIDC interaction binding, or null for standalone work. */
+    readonly interactionUid: string | null;
+    /** Keyed, domain-separated request idempotency digest. */
+    readonly idempotencyDigest: string;
+    /** Current durable lifecycle state. */
+    readonly status: RecoveryJobStatus;
+    /** Earliest claim time. */
+    readonly availableAt: Date;
+    /** Time at which the current worker claimed the job. */
+    readonly claimedAt: Date | null;
+    /** Current worker owner identifier. */
+    readonly claimedBy: string | null;
+    /** Number of processing attempts already started. */
+    readonly attemptCount: number;
+    /** Closed failure reason from the latest unsuccessful attempt. */
+    readonly lastFailureReason: string | null;
+    /** Terminal transition time. */
+    readonly completedAt: Date | null;
+    /** Job creation time. */
+    readonly createdAt: Date;
+    /** Latest durable transition time. */
+    readonly updatedAt: Date;
+}
+/** Recovery job returned from an atomic claim with its acquisition reason. */
+export interface ClaimedRecoveryJob extends RecoveryJob {
+    /**
+     * How this worker acquired the row. An exhausted lease must be terminally closed without
+     * performing account-specific work because the prior fifth attempt has an unknown outcome.
+     */
+    readonly claimDisposition: 'available' | 'lease_reclaimed' | 'lease_exhausted';
+}
+/** Result of an idempotent enqueue operation. */
+export interface EnqueueRecoveryJobResult {
+    /** Durable row representing the request. */
+    readonly job: RecoveryJob;
+    /** Whether this call inserted the row rather than observing an existing idempotency match. */
+    readonly inserted: boolean;
+}
+/** Input for one bounded atomic claim operation. */
+export interface ClaimRecoveryJobsInput {
+    /** Unique worker-process identifier. */
+    readonly workerId: string;
+    /** Repository clock value used for every row in the transition. */
+    readonly now: Date;
+    /** Claims at or before this instant may be reclaimed. */
+    readonly leaseExpiredBefore: Date;
+    /** Maximum jobs to claim, bounded to the product policy maximum. */
+    readonly limit?: number;
+}
+/** Input for charging one processing attempt against an owned claim. */
+export interface BeginRecoveryJobAttemptInput {
+    /** Durable job identifier. */
+    readonly jobId: string;
+    /** Worker that currently owns the claim. */
+    readonly workerId: string;
+    /** Repository clock value used for the transition. */
+    readonly now: Date;
+}
+/** Input for returning an owned claim to the available queue. */
+export interface RetryRecoveryJobInput {
+    /** Durable job identifier. */
+    readonly jobId: string;
+    /** Worker that currently owns the claim. */
+    readonly workerId: string;
+    /** Earliest time at which the retry may be claimed. */
+    readonly availableAt: Date;
+    /** Closed privacy-safe failure reason. */
+    readonly reason: string;
+    /** Repository clock value used for the transition. */
+    readonly now: Date;
+}
+/** Input for a terminal owned-claim transition. */
+export interface FinishRecoveryJobInput {
+    /** Durable job identifier. */
+    readonly jobId: string;
+    /** Worker that currently owns the claim. */
+    readonly workerId: string;
+    /** Repository clock value used for the transition. */
+    readonly now: Date;
+    /** Closed reason required for terminal failure and omitted for success. */
+    readonly reason?: string;
+}
+/** Minimal query boundary shared by PostgreSQL pools and transaction clients. */
+export interface RecoveryJobDatabase {
+    /** Execute one parameterized query. */
+    query<Row extends QueryResultRow = QueryResultRow>(text: string, values?: readonly unknown[]): Promise<QueryResult<Row>>;
+}
+/**
+ * Create a durable recovery-job repository.
+ *
+ * Passing a transaction client keeps enqueue operations composable with a request-owned
+ * transaction. Omitting the argument uses Porta's connected application pool.
+ *
+ * @param database - PostgreSQL pool or transaction client.
+ * @returns Typed repository for durable recovery work.
+ */
+export declare function createRecoveryJobRepository(database?: RecoveryJobDatabase): RecoveryJobRepository;
+/** PostgreSQL implementation of durable recovery-work transitions. */
+export declare class RecoveryJobRepository {
+    /** Query boundary used by every repository operation. */
+    protected readonly database: RecoveryJobDatabase;
+    /**
+     * Create a repository over a pool or existing transaction.
+     *
+     * @param database - Parameterized PostgreSQL query boundary.
+     */
+    constructor(database: RecoveryJobDatabase);
+    /**
+     * Insert one durable job or return the existing idempotency match.
+     *
+     * @param input - Protected tenant-bound recovery request.
+     * @returns Durable row and whether this invocation inserted it.
+     */
+    enqueue(input: EnqueueRecoveryJobInput): Promise<EnqueueRecoveryJobResult>;
+    /**
+     * Atomically lease a bounded batch of available or lease-expired jobs.
+     *
+     * Leasing does not charge a processing attempt. The worker starts each attempt separately, just
+     * before invoking account-specific work, so a crash while walking a batch cannot consume the
+     * retry budget of jobs it never started.
+     *
+     * @param input - Worker identity, clock, lease cutoff, and optional bound.
+     * @returns Claimed rows with an explicit fresh, reclaimed, or exhausted-lease disposition.
+     */
+    claimAvailable(input: ClaimRecoveryJobsInput): Promise<readonly ClaimedRecoveryJob[]>;
+    /**
+     * Charge one processing attempt immediately before an owned job is processed.
+     *
+     * @param input - Owned job identity and repository clock.
+     * @returns The updated claimed row, or null when ownership was lost or the budget is exhausted.
+     */
+    beginAttempt(input: BeginRecoveryJobAttemptInput): Promise<RecoveryJob | null>;
+    /**
+     * Return an owned claim to the queue after a transient failure.
+     *
+     * @param input - Owned job, retry time, closed reason, and repository clock.
+     * @returns True only when the caller still owned the claim.
+     */
+    scheduleRetry(input: RetryRecoveryJobInput): Promise<boolean>;
+    /**
+     * Mark an owned claim complete after its external effects settle.
+     *
+     * @param input - Owned job and repository clock; reason must be omitted.
+     * @returns True only when the caller still owned the claim.
+     */
+    markCompleted(input: FinishRecoveryJobInput): Promise<boolean>;
+    /**
+     * Mark an owned claim terminally failed with a closed privacy-safe reason.
+     *
+     * @param input - Owned job, repository clock, and required closed reason.
+     * @returns True only when the caller still owned the claim.
+     */
+    markTerminalFailure(input: FinishRecoveryJobInput): Promise<boolean>;
+}
+/** PostgreSQL clients accepted by the repository factory. */
+export type RecoveryJobPostgresClient = Pool | PoolClient;
+//# sourceMappingURL=recovery-job-repository.d.ts.map

package/dist/auth/recovery-job-repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-job-repository.d.ts","sourceRoot":"","sources":["../../src/auth/recovery-job-repository.ts"],"names":[],"mappings":"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"}

package/dist/auth/recovery-job-repository.js

@@ -0,0 +1,340 @@
+/**
+ * Durable PostgreSQL repository for account-recovery work.
+ *
+ * Public request handlers enqueue only protected, tenant-bound input. A worker later claims a
+ * bounded batch and performs account-specific work outside the request path. Every transition is
+ * conditional on the current claim owner so a stale worker cannot complete or reschedule work
+ * reclaimed by another process.
+ */
+import { z } from 'zod';
+import { getPool } from '../lib/database.js';
+/** Closed recovery operations accepted by the durable queue. */
+export const RECOVERY_JOB_TYPES = ['magic_link', 'password_reset'];
+/** Closed durable lifecycle states for recovery work. */
+export const RECOVERY_JOB_STATUSES = [
+    'available',
+    'claimed',
+    'completed',
+    'terminal_failure',
+];
+/** Maximum number of jobs one worker pass may claim. */
+export const RECOVERY_JOB_CLAIM_LIMIT = 25;
+/** Maximum processing attempts retained by the durable schema. */
+export const RECOVERY_JOB_ATTEMPT_LIMIT = 5;
+const uuidSchema = z.string().uuid();
+const protectedTextSchema = z
+    .string()
+    .min(1)
+    .max(4096)
+    .regex(/^[A-Za-z0-9_-]+$/);
+const keyIdSchema = z.string().regex(/^[A-Za-z0-9_-]{8,64}$/);
+const digestSchema = z.string().regex(/^[0-9a-f]{64}$/);
+const interactionUidSchema = z.string().min(1).max(128).nullable();
+const reasonSchema = z.string().regex(/^[a-z][a-z0-9_]{0,63}$/);
+const enqueueSchema = z
+    .object({
+    jobType: z.enum(RECOVERY_JOB_TYPES),
+    organizationId: uuidSchema,
+    protectedAddress: z
+        .object({
+        ciphertext: protectedTextSchema,
+        iv: protectedTextSchema,
+        tag: protectedTextSchema,
+        keyId: keyIdSchema,
+    })
+        .strict(),
+    interactionUid: interactionUidSchema,
+    idempotencyDigest: digestSchema,
+    availableAt: z.date(),
+})
+    .strict()
+    .superRefine((input, context) => {
+    const interactionMatchesType = input.jobType === 'magic_link' ||
+        (input.jobType === 'password_reset' && input.interactionUid === null);
+    if (!interactionMatchesType) {
+        context.addIssue({
+            code: 'custom',
+            path: ['interactionUid'],
+            message: 'interaction binding does not match the recovery job type',
+        });
+    }
+});
+const claimSchema = z
+    .object({
+    workerId: uuidSchema,
+    now: z.date(),
+    leaseExpiredBefore: z.date(),
+    limit: z.number().int().min(1).max(RECOVERY_JOB_CLAIM_LIMIT).default(RECOVERY_JOB_CLAIM_LIMIT),
+})
+    .strict()
+    .refine((input) => input.leaseExpiredBefore.getTime() <= input.now.getTime(), {
+    path: ['leaseExpiredBefore'],
+    message: 'lease expiry cutoff cannot be later than the repository clock',
+});
+const retrySchema = z
+    .object({
+    jobId: uuidSchema,
+    workerId: uuidSchema,
+    availableAt: z.date(),
+    reason: reasonSchema,
+    now: z.date(),
+})
+    .strict()
+    .refine((input) => input.availableAt.getTime() >= input.now.getTime(), {
+    path: ['availableAt'],
+    message: 'retry availability cannot precede the repository clock',
+});
+const beginAttemptSchema = z
+    .object({
+    jobId: uuidSchema,
+    workerId: uuidSchema,
+    now: z.date(),
+})
+    .strict();
+const finishSchema = z
+    .object({
+    jobId: uuidSchema,
+    workerId: uuidSchema,
+    now: z.date(),
+    reason: reasonSchema.optional(),
+})
+    .strict();
+const JOB_COLUMNS = `
+  id, job_type, organization_id,
+  address_ciphertext, address_iv, address_tag, address_key_id,
+  interaction_uid, idempotency_digest, status, available_at,
+  claimed_at, claimed_by, attempt_count, last_failure_reason,
+  completed_at, created_at, updated_at
+`;
+const QUALIFIED_JOB_COLUMNS = `
+  job.id, job.job_type, job.organization_id,
+  job.address_ciphertext, job.address_iv, job.address_tag, job.address_key_id,
+  job.interaction_uid, job.idempotency_digest, job.status, job.available_at,
+  job.claimed_at, job.claimed_by, job.attempt_count, job.last_failure_reason,
+  job.completed_at, job.created_at, job.updated_at
+`;
+/** Map one database row to the public repository model. */
+function mapRecoveryJob(row) {
+    return {
+        id: row.id,
+        jobType: row.job_type,
+        organizationId: row.organization_id,
+        protectedAddress: {
+            ciphertext: row.address_ciphertext,
+            iv: row.address_iv,
+            tag: row.address_tag,
+            keyId: row.address_key_id,
+        },
+        interactionUid: row.interaction_uid,
+        idempotencyDigest: row.idempotency_digest,
+        status: row.status,
+        availableAt: row.available_at,
+        claimedAt: row.claimed_at,
+        claimedBy: row.claimed_by,
+        attemptCount: row.attempt_count,
+        lastFailureReason: row.last_failure_reason,
+        completedAt: row.completed_at,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+/**
+ * Create a durable recovery-job repository.
+ *
+ * Passing a transaction client keeps enqueue operations composable with a request-owned
+ * transaction. Omitting the argument uses Porta's connected application pool.
+ *
+ * @param database - PostgreSQL pool or transaction client.
+ * @returns Typed repository for durable recovery work.
+ */
+export function createRecoveryJobRepository(database = getPool()) {
+    return new RecoveryJobRepository(database);
+}
+/** PostgreSQL implementation of durable recovery-work transitions. */
+export class RecoveryJobRepository {
+    /** Query boundary used by every repository operation. */
+    database;
+    /**
+     * Create a repository over a pool or existing transaction.
+     *
+     * @param database - Parameterized PostgreSQL query boundary.
+     */
+    constructor(database) {
+        this.database = database;
+    }
+    /**
+     * Insert one durable job or return the existing idempotency match.
+     *
+     * @param input - Protected tenant-bound recovery request.
+     * @returns Durable row and whether this invocation inserted it.
+     */
+    async enqueue(input) {
+        const parsed = enqueueSchema.parse(input);
+        const result = await this.database.query(`INSERT INTO auth_recovery_jobs (
+         job_type, organization_id,
+         address_ciphertext, address_iv, address_tag, address_key_id,
+         interaction_uid, idempotency_digest, available_at
+       ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+       ON CONFLICT (organization_id, job_type, idempotency_digest) DO NOTHING
+       RETURNING ${JOB_COLUMNS}`, [
+            parsed.jobType,
+            parsed.organizationId,
+            parsed.protectedAddress.ciphertext,
+            parsed.protectedAddress.iv,
+            parsed.protectedAddress.tag,
+            parsed.protectedAddress.keyId,
+            parsed.interactionUid,
+            parsed.idempotencyDigest,
+            parsed.availableAt,
+        ]);
+        if (result.rows[0]) {
+            return { job: mapRecoveryJob(result.rows[0]), inserted: true };
+        }
+        const existing = await this.database.query(`SELECT ${JOB_COLUMNS}
+       FROM auth_recovery_jobs
+       WHERE organization_id = $1
+         AND job_type = $2
+         AND idempotency_digest = $3`, [parsed.organizationId, parsed.jobType, parsed.idempotencyDigest]);
+        if (!existing.rows[0]) {
+            throw new Error('Recovery job idempotency row disappeared after insert conflict');
+        }
+        return { job: mapRecoveryJob(existing.rows[0]), inserted: false };
+    }
+    /**
+     * Atomically lease a bounded batch of available or lease-expired jobs.
+     *
+     * Leasing does not charge a processing attempt. The worker starts each attempt separately, just
+     * before invoking account-specific work, so a crash while walking a batch cannot consume the
+     * retry budget of jobs it never started.
+     *
+     * @param input - Worker identity, clock, lease cutoff, and optional bound.
+     * @returns Claimed rows with an explicit fresh, reclaimed, or exhausted-lease disposition.
+     */
+    async claimAvailable(input) {
+        const parsed = claimSchema.parse(input);
+        const result = await this.database.query(`WITH candidates AS (
+         SELECT id, status AS previous_status, attempt_count AS previous_attempt_count
+         FROM auth_recovery_jobs
+         WHERE (status = 'available' AND available_at <= $1 AND attempt_count < $5)
+            OR (status = 'claimed' AND claimed_at <= $2 AND attempt_count <= $5)
+         ORDER BY COALESCE(claimed_at, available_at), created_at, id
+         LIMIT $3
+         FOR UPDATE SKIP LOCKED
+       )
+       UPDATE auth_recovery_jobs AS job
+       SET status = 'claimed',
+           claimed_at = $1,
+           claimed_by = $4,
+           last_failure_reason = NULL,
+           completed_at = NULL,
+           updated_at = $1
+       FROM candidates
+       WHERE job.id = candidates.id
+       RETURNING ${QUALIFIED_JOB_COLUMNS},
+         CASE
+           WHEN candidates.previous_status = 'available' THEN 'available'
+           WHEN candidates.previous_attempt_count >= $5 THEN 'lease_exhausted'
+           ELSE 'lease_reclaimed'
+         END AS claim_disposition`, [
+            parsed.now,
+            parsed.leaseExpiredBefore,
+            parsed.limit,
+            parsed.workerId,
+            RECOVERY_JOB_ATTEMPT_LIMIT,
+        ]);
+        return result.rows.map((row) => ({
+            ...mapRecoveryJob(row),
+            claimDisposition: row.claim_disposition,
+        }));
+    }
+    /**
+     * Charge one processing attempt immediately before an owned job is processed.
+     *
+     * @param input - Owned job identity and repository clock.
+     * @returns The updated claimed row, or null when ownership was lost or the budget is exhausted.
+     */
+    async beginAttempt(input) {
+        const parsed = beginAttemptSchema.parse(input);
+        const result = await this.database.query(`UPDATE auth_recovery_jobs
+       SET attempt_count = attempt_count + 1,
+           updated_at = $3
+       WHERE id = $1
+         AND claimed_by = $2
+         AND status = 'claimed'
+         AND attempt_count < $4
+       RETURNING ${JOB_COLUMNS}`, [parsed.jobId, parsed.workerId, parsed.now, RECOVERY_JOB_ATTEMPT_LIMIT]);
+        return result.rows[0] ? mapRecoveryJob(result.rows[0]) : null;
+    }
+    /**
+     * Return an owned claim to the queue after a transient failure.
+     *
+     * @param input - Owned job, retry time, closed reason, and repository clock.
+     * @returns True only when the caller still owned the claim.
+     */
+    async scheduleRetry(input) {
+        const parsed = retrySchema.parse(input);
+        const result = await this.database.query(`UPDATE auth_recovery_jobs
+       SET status = 'available',
+           available_at = $3,
+           claimed_at = NULL,
+           claimed_by = NULL,
+           last_failure_reason = $4,
+           updated_at = $5
+       WHERE id = $1
+         AND claimed_by = $2
+         AND status = 'claimed'
+         AND attempt_count < $6`, [
+            parsed.jobId,
+            parsed.workerId,
+            parsed.availableAt,
+            parsed.reason,
+            parsed.now,
+            RECOVERY_JOB_ATTEMPT_LIMIT,
+        ]);
+        return result.rowCount === 1;
+    }
+    /**
+     * Mark an owned claim complete after its external effects settle.
+     *
+     * @param input - Owned job and repository clock; reason must be omitted.
+     * @returns True only when the caller still owned the claim.
+     */
+    async markCompleted(input) {
+        const parsed = finishSchema.parse(input);
+        if (parsed.reason !== undefined) {
+            throw new Error('Completed recovery jobs cannot carry a failure reason');
+        }
+        const result = await this.database.query(`UPDATE auth_recovery_jobs
+       SET status = 'completed',
+           claimed_at = NULL,
+           claimed_by = NULL,
+           last_failure_reason = NULL,
+           completed_at = $3,
+           updated_at = $3
+       WHERE id = $1
+         AND claimed_by = $2
+         AND status = 'claimed'`, [parsed.jobId, parsed.workerId, parsed.now]);
+        return result.rowCount === 1;
+    }
+    /**
+     * Mark an owned claim terminally failed with a closed privacy-safe reason.
+     *
+     * @param input - Owned job, repository clock, and required closed reason.
+     * @returns True only when the caller still owned the claim.
+     */
+    async markTerminalFailure(input) {
+        const parsed = finishSchema.extend({ reason: reasonSchema }).parse(input);
+        const result = await this.database.query(`UPDATE auth_recovery_jobs
+       SET status = 'terminal_failure',
+           claimed_at = NULL,
+           claimed_by = NULL,
+           last_failure_reason = $3,
+           completed_at = $4,
+           updated_at = $4
+       WHERE id = $1
+         AND claimed_by = $2
+         AND status = 'claimed'`, [parsed.jobId, parsed.workerId, parsed.reason, parsed.now]);
+        return result.rowCount === 1;
+    }
+}
+//# sourceMappingURL=recovery-job-repository.js.map

package/dist/auth/recovery-job-repository.js.map

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

package/dist/auth/recovery-service.d.ts

@@ -0,0 +1,27 @@
+/** Public enqueue and application lifecycle boundary for durable recovery work. */
+import { type EnqueueRecoveryJobResult, type RecoveryJobType } from './recovery-job-repository.js';
+import { type InteractionAuthorityProvider } from './interaction-authority.js';
+/** Input accepted after public validation, CSRF, and rate limiting. */
+export interface EnqueueAccountRecoveryInput {
+    /** Closed recovery operation. */
+    readonly jobType: RecoveryJobType;
+    /** Resolved tenant UUID. */
+    readonly organizationId: string;
+    /** Publicly submitted recovery address. */
+    readonly email: string;
+    /** Interaction binding for magic links, otherwise null. */
+    readonly interactionUid: string | null;
+    /** Per-form CSRF value that identifies one admitted action without storing it. */
+    readonly actionNonce: string;
+}
+/** Protect and durably enqueue one account-independent recovery request. */
+export declare function enqueueAccountRecovery(input: EnqueueAccountRecoveryInput): Promise<EnqueueRecoveryJobResult>;
+/**
+ * Start the singleton recovery worker after all application dependencies are ready.
+ *
+ * @param provider - Live provider authority required by interaction-bound magic-link jobs.
+ */
+export declare function startAccountRecoveryWorker(provider?: InteractionAuthorityProvider): void;
+/** Stop accepting claims and await the bounded active-cycle settlement window. */
+export declare function stopAccountRecoveryWorker(): Promise<boolean>;
+//# sourceMappingURL=recovery-service.d.ts.map

package/dist/auth/recovery-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-service.d.ts","sourceRoot":"","sources":["../../src/auth/recovery-service.ts"],"names":[],"mappings":"AAAA,mFAAmF;AAGnF,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACrB,MAAM,8BAA8B,CAAC;AAOtC,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,4BAA4B,CAAC;AAEpC,uEAAuE;AACvE,MAAM,WAAW,2BAA2B;IAC1C,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,4BAA4B;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAID,4EAA4E;AAC5E,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAqBnC;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,CAAC,EAAE,4BAA4B,GAAG,IAAI,CASxF;AAED,kFAAkF;AAClF,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,OAAO,CAAC,CAKlE"}

package/dist/auth/recovery-service.js

@@ -0,0 +1,53 @@
+/** Public enqueue and application lifecycle boundary for durable recovery work. */
+import { createAccountRecoveryJobProcessor } from './recovery-job-processor.js';
+import { createRecoveryJobRepository, } from './recovery-job-repository.js';
+import { normalizeRecoveryAddress, protectRecoveryAddress, recoveryIdempotencyDigest, } from './recovery-crypto.js';
+import { createRecoveryWorker } from './recovery-worker.js';
+import { createInteractionAuthorityResolver, } from './interaction-authority.js';
+let worker = null;
+/** Protect and durably enqueue one account-independent recovery request. */
+export async function enqueueAccountRecovery(input) {
+    const requestAuthority = {
+        organizationId: input.organizationId,
+        jobType: input.jobType,
+        interactionUid: input.interactionUid,
+    };
+    const normalized = normalizeRecoveryAddress(input.email);
+    const idempotencyDigest = recoveryIdempotencyDigest(requestAuthority, input.actionNonce);
+    const result = await createRecoveryJobRepository().enqueue({
+        jobType: input.jobType,
+        organizationId: input.organizationId,
+        protectedAddress: protectRecoveryAddress(normalized, {
+            ...requestAuthority,
+            idempotencyDigest,
+        }),
+        interactionUid: input.interactionUid,
+        idempotencyDigest,
+        availableAt: new Date(),
+    });
+    worker?.wake();
+    return result;
+}
+/**
+ * Start the singleton recovery worker after all application dependencies are ready.
+ *
+ * @param provider - Live provider authority required by interaction-bound magic-link jobs.
+ */
+export function startAccountRecoveryWorker(provider) {
+    if (worker)
+        return;
+    worker = createRecoveryWorker({
+        repository: createRecoveryJobRepository(),
+        processor: createAccountRecoveryJobProcessor(provider ? createInteractionAuthorityResolver(provider) : undefined),
+    });
+    worker.start();
+}
+/** Stop accepting claims and await the bounded active-cycle settlement window. */
+export async function stopAccountRecoveryWorker() {
+    const active = worker;
+    if (!active)
+        return true;
+    worker = null;
+    return active.stop();
+}
+//# sourceMappingURL=recovery-service.js.map

package/dist/auth/recovery-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-service.js","sourceRoot":"","sources":["../../src/auth/recovery-service.ts"],"names":[],"mappings":"AAAA,mFAAmF;AAEnF,OAAO,EAAE,iCAAiC,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EACL,2BAA2B,GAG5B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAuB,MAAM,sBAAsB,CAAC;AACjF,OAAO,EACL,kCAAkC,GAEnC,MAAM,4BAA4B,CAAC;AAgBpC,IAAI,MAAM,GAA0B,IAAI,CAAC;AAEzC,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,KAAkC;IAElC,MAAM,gBAAgB,GAAG;QACvB,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,cAAc,EAAE,KAAK,CAAC,cAAc;KAC5B,CAAC;IACX,MAAM,UAAU,GAAG,wBAAwB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACzD,MAAM,iBAAiB,GAAG,yBAAyB,CAAC,gBAAgB,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IACzF,MAAM,MAAM,GAAG,MAAM,2BAA2B,EAAE,CAAC,OAAO,CAAC;QACzD,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,gBAAgB,EAAE,sBAAsB,CAAC,UAAU,EAAE;YACnD,GAAG,gBAAgB;YACnB,iBAAiB;SAClB,CAAC;QACF,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,iBAAiB;QACjB,WAAW,EAAE,IAAI,IAAI,EAAE;KACxB,CAAC,CAAC;IACH,MAAM,EAAE,IAAI,EAAE,CAAC;IACf,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAAuC;IAChF,IAAI,MAAM;QAAE,OAAO;IACnB,MAAM,GAAG,oBAAoB,CAAC;QAC5B,UAAU,EAAE,2BAA2B,EAAE;QACzC,SAAS,EAAE,iCAAiC,CAC1C,QAAQ,CAAC,CAAC,CAAC,kCAAkC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CACpE;KACF,CAAC,CAAC;IACH,MAAM,CAAC,KAAK,EAAE,CAAC;AACjB,CAAC;AAED,kFAAkF;AAClF,MAAM,CAAC,KAAK,UAAU,yBAAyB;IAC7C,MAAM,MAAM,GAAG,MAAM,CAAC;IACtB,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,GAAG,IAAI,CAAC;IACd,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;AACvB,CAAC"}