@jimhoyd/urlcode-auth 0.1.0-alpha.1 → 0.1.0-alpha.2

package/dist/auth-core.d.ts

@@ -0,0 +1,655 @@
+import type { AdminAccountService } from './admin-account-operations.ts';
+import type { AuthAbuseOptions, AuthAbusePolicy } from './abuse.ts';
+import type { UserQuery } from './user-query.ts';
+import type { ManualRecoveryService, ManualRecoveryCase } from './manual-recovery.ts';
+import type { FactorRecoveryService } from './factor-recovery.ts';
+import type { RegistrationPolicy, RegistrationInput, RegistrationProfile, RegistrationOptions } from './registration.ts';
+import { AuthError } from './auth-store.ts';
+export { AuthError };
+export interface AuthUser {
+    /** Latest retained device/session observation; not complete historical activity. */
+    observedLastSeen?: number;
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    status: 'active' | 'locked' | 'pending-delete';
+    roles: string[];
+    created: number;
+    totpEnabled: boolean;
+    passkeyMfaEnabled?: boolean;
+    profile?: RegistrationProfile;
+}
+export type AuthRestriction = 'verify-email' | 'enroll-mfa';
+export interface AuthSecondFactor {
+    token: string;
+    browserHash: string;
+}
+export interface AuthSecurityPolicy {
+    abuse?: AuthAbusePolicy;
+    allowPasskeySecondFactor?: true;
+    trustedDeviceTtlMs?: number;
+    allowEmailFactorRecovery?: true;
+    allowManualRecovery?: true;
+    requireEmailVerification: boolean;
+    requireMfa: boolean;
+    deletionGraceMs: number;
+}
+export interface AuthPrincipal {
+    restrictions?: AuthRestriction[];
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    roles: string[];
+    permissions: string[];
+    sessionId: string;
+    authenticatedAt: number;
+    impersonatorId?: string;
+}
+export interface ExternalAuthProof {
+    kind: 'oidc';
+    version: number;
+    provider: string;
+    subject: string;
+}
+export interface PasskeyAuthProof {
+    kind: 'passkey';
+    version: number;
+    credentialId: string;
+    publicKeyHash: string;
+    expectedCounter: number;
+    newCounter: number;
+}
+export type AuthProof = ExternalAuthProof | PasskeyAuthProof;
+export interface AuthDevice {
+    id: string;
+    label?: string;
+}
+export interface AuthSessionResult {
+    newDevice?: boolean;
+    user: AuthUser;
+    token: string;
+    principal: AuthPrincipal;
+}
+export interface AuthSession {
+    id: string;
+    created: number;
+    authenticatedAt: number;
+    expires: number;
+    lastSeen?: number;
+    deviceLabel?: string;
+}
+export interface AuthDailyMetric {
+    day: string;
+    signUps: number;
+    signIns: number;
+    failedSignIns: number;
+    methods: {
+        method: string;
+        signUps: number;
+        signIns: number;
+        failedSignIns: number;
+    }[];
+}
+export interface AuthAuditEvent {
+    id: number;
+    actor: string;
+    action: string;
+    subject: string;
+    created: number;
+    reason: string;
+}
+export interface AuthLifecycleEvent {
+    type: 'sign-up' | 'delete';
+    accountId: string;
+}
+export interface AuthHookStats {
+    accepted: number;
+    dropped: number;
+    failed: number;
+    timedOut: number;
+}
+export interface AuthOptions {
+    abuse?: AuthAbuseOptions;
+    blockDisposableEmails?: boolean;
+    allowPasskeySecondFactor?: boolean;
+    trustedDeviceTtlMs?: number;
+    /** Explicit email fallback lowers MFA assurance; disabled by default. */
+    allowEmailFactorRecovery?: boolean;
+    allowManualRecovery?: boolean;
+    approveConfigurationChangeFrom?: string;
+    configurationTag?: string;
+    requireEmailVerification?: boolean;
+    requireMfa?: boolean;
+    deletionGraceMs?: number;
+    onLifecycle?: (event: AuthLifecycleEvent, context: {
+        signal: AbortSignal;
+    }) => void | Promise<void>;
+    database: string;
+    encryptionKey?: Uint8Array;
+    encryptionKeys?: Record<string, Uint8Array>;
+    activeEncryptionKey?: string;
+    roles: Record<string, string[]>;
+    defaultRole?: string;
+    now?: () => number;
+    registrationPolicy?: RegistrationPolicy;
+    sessionTtlMs?: number;
+    sessionIdleMs?: number;
+    allowImpersonation?: boolean;
+    registrationMode?: 'open' | 'invite-only' | 'waitlist' | 'off';
+    allowedEmails?: string[];
+    blockedEmails?: string[];
+    checkPassword?: (password: string, context?: {
+        signal: AbortSignal;
+    }) => Promise<void>;
+    allowedEmailDomains?: string[];
+    blockedEmailDomains?: string[];
+}
+export interface AuthCredentials {
+    secondFactor?: AuthSecondFactor;
+    trustedDevice?: string;
+    device?: AuthDevice;
+    email: string;
+    password: string;
+    totp?: string;
+    recoveryCode?: string;
+}
+export interface AuthPasskey {
+    secondFactor?: boolean;
+    id: string;
+    accountId: string;
+    publicKey: string;
+    counter: number;
+    transports?: string[];
+}
+export interface AuthCase {
+    id: string;
+    accountId: string;
+    action: 'reset-factors' | 'lock' | 'unlock' | 'roles' | 'restore-access';
+    recovery?: ManualRecoveryCase['recovery'];
+    roles?: string[];
+    reason: string;
+    makerId: string;
+    approverId?: string;
+    status: 'pending' | 'applied' | 'closed';
+    notes?: {
+        actorId: string;
+        note: string;
+        created: number;
+    }[];
+    created: number;
+    expires: number;
+    targetVersion: number;
+}
+export interface SignupBinding {
+    flowId: string;
+    browserHash: string;
+}
+export interface SignupState {
+    flowId: string;
+    accountId: string;
+    email: string;
+    step: 'verify-email' | 'credential' | 'profile';
+    expires: number;
+}
+export interface SignupStart extends SignupState {
+    delivery?: {
+        kind: 'signup-code';
+        email: string;
+        code: string;
+    } | {
+        kind: 'registration-attempt';
+        email: string;
+    };
+}
+export interface AuthService extends FactorRecoveryService, ManualRecoveryService, AdminAccountService {
+    getAbusePolicy(): AuthAbusePolicy | undefined;
+    admitAuthRequest(input: {
+        client: string | null;
+        signupEmail?: string;
+    }): Promise<{
+        challengeRequired: boolean;
+    }>;
+    createSecondFactorProof(input: {
+        browserHash: string;
+        proof: PasskeyAuthProof;
+    }): Promise<string>;
+    setPasskeySecondFactor(input: {
+        token: string;
+        credentialId: string;
+        enabled: boolean;
+        secondFactor?: AuthSecondFactor;
+    }): Promise<void>;
+    rememberDevice(input: {
+        token: string;
+        label?: string;
+    }): Promise<{
+        token: string;
+        expires: number;
+    }>;
+    listTrustedDevices(token: string): Promise<{
+        id: string;
+        label: string;
+        created: number;
+        expires: number;
+    }[]>;
+    revokeTrustedDevice(input: {
+        token: string;
+        deviceId: string;
+    }): Promise<void>;
+    beginSignup(input: {
+        email: string;
+        browserHash: string;
+        invitationToken?: string;
+    }): Promise<SignupStart>;
+    getSignup(input: SignupBinding): Promise<SignupState | null>;
+    verifySignup(input: SignupBinding & {
+        code: string;
+    }): Promise<SignupState>;
+    setSignupPassword(input: SignupBinding & {
+        password: string;
+    }): Promise<SignupState>;
+    setSignupPasskeyChallenge(input: SignupBinding & {
+        challenge: string;
+    }): Promise<SignupState>;
+    getSignupPasskeyChallenge(input: SignupBinding): Promise<{
+        state: SignupState;
+        challenge: string;
+    }>;
+    setSignupPasskey(input: SignupBinding & {
+        challenge: string;
+        credential: Omit<AuthPasskey, 'accountId'>;
+    }): Promise<SignupState>;
+    completeSignup(input: SignupBinding & {
+        profile?: RegistrationInput;
+        device?: AuthDevice;
+    }): Promise<AuthSessionResult | null>;
+    register(input: {
+        email: string;
+        password: string;
+        invitationToken?: string;
+        device?: AuthDevice;
+        profile?: RegistrationInput;
+    }): Promise<AuthSessionResult>;
+    bootstrapAdmin(input: {
+        email: string;
+        password: string;
+    }): Promise<AuthSessionResult>;
+    login(input: AuthCredentials): Promise<AuthSessionResult>;
+    stepUp(input: {
+        token: string;
+        password: string;
+        totp?: string;
+        recoveryCode?: string;
+        secondFactor?: AuthSecondFactor;
+    }): Promise<AuthSessionResult>;
+    authenticate(token: string): Promise<AuthPrincipal | null>;
+    logout(token: string): Promise<void>;
+    revokeSessions(accountId: string): Promise<void>;
+    listUsers(options?: UserQuery): Promise<{
+        users: AuthUser[];
+        next?: string;
+    }>;
+    getUser(id: string): Promise<AuthUser | null>;
+    getRoles(): Record<string, string[]>;
+    listSessions(accountId: string): Promise<AuthSession[]>;
+    listDevices(accountId: string): Promise<{
+        id: string;
+        label: string;
+        lastSeen: number;
+    }[]>;
+    listAudit(options?: {
+        limit?: number;
+        after?: string;
+        actor?: string;
+        subject?: string;
+        action?: string;
+        from?: number;
+        to?: number;
+    }): Promise<{
+        events: AuthAuditEvent[];
+        next?: string;
+    }>;
+    issueToken(input: {
+        email: string;
+        purpose: 'verify-email' | 'reset-password';
+    }): Promise<{
+        token: string | null;
+    }>;
+    consumeVerification(token: string): Promise<AuthUser>;
+    resetPassword(input: {
+        token: string;
+        password: string;
+    }): Promise<AuthUser>;
+    beginTotp(token: string): Promise<{
+        secret: string;
+        otpauthUrl: string;
+    }>;
+    confirmTotp(input: {
+        token: string;
+        code: string;
+    }): Promise<{
+        recoveryCodes: string[];
+    }>;
+    disableTotp(input: {
+        token: string;
+        password: string;
+        code?: string;
+        secondFactor?: AuthSecondFactor;
+    }): Promise<void>;
+    adminSetRoles(input: {
+        actorToken: string;
+        accountId: string;
+        roles: string[];
+        reason?: string;
+    }): Promise<AuthUser>;
+    adminSetStatus(input: {
+        actorToken: string;
+        accountId: string;
+        status: 'active' | 'locked';
+        reason?: string;
+    }): Promise<AuthUser>;
+    adminRevokeSessions(input: {
+        actorToken: string;
+        accountId: string;
+        reason?: string;
+    }): Promise<void>;
+    putFlow(input: {
+        id: string;
+        kind: string;
+        data: unknown;
+        expires: number;
+    }): Promise<void>;
+    consumeFlow(id: string, kind: string): Promise<unknown | null>;
+    findExternal(provider: string, subject: string): Promise<AuthUser | null>;
+    linkExternal(input: {
+        actorToken: string;
+        provider: string;
+        subject: string;
+    }): Promise<void>;
+    createExternalAccount(input: {
+        email: string;
+        provider: string;
+        subject: string;
+        emailVerified: boolean;
+        profile?: RegistrationInput;
+    }): Promise<AuthUser>;
+    getExternalProof(provider: string, subject: string): Promise<{
+        user: AuthUser;
+        proof: ExternalAuthProof;
+    } | null>;
+    issueSession(accountId: string, input: {
+        trustedDevice?: string;
+        method: 'passkey' | 'oidc';
+        proof: AuthProof;
+        device?: AuthDevice;
+        totp?: string;
+        recoveryCode?: string;
+        secondFactor?: AuthSecondFactor;
+    }): Promise<AuthSessionResult>;
+    addPasskey(input: {
+        actorToken: string;
+        credential: Omit<AuthPasskey, 'accountId'>;
+    }): Promise<void>;
+    getPasskey(id: string): Promise<{
+        accountId: string;
+        credential: Omit<AuthPasskey, 'accountId'>;
+        proof: Omit<PasskeyAuthProof, 'newCounter'>;
+    } | null>;
+    listPasskeys(accountId: string): Promise<Omit<AuthPasskey, 'accountId'>[]>;
+    advancePasskeyCounter(input: {
+        id: string;
+        expectedCounter: number;
+        newCounter: number;
+    }): Promise<void>;
+    changePassword(input: {
+        token: string;
+        currentPassword: string;
+        password: string;
+        totp?: string;
+        recoveryCode?: string;
+        secondFactor?: AuthSecondFactor;
+    }): Promise<void>;
+    exportAccount(token: string): Promise<{
+        user: AuthUser;
+        sessions: AuthSession[];
+        passkeys: {
+            id: string;
+            transports?: string[];
+        }[];
+        identities: {
+            provider: string;
+            subject: string;
+        }[];
+    }>;
+    deleteAccount(input: {
+        token: string;
+        password?: string;
+        totp?: string;
+        recoveryCode?: string;
+        secondFactor?: AuthSecondFactor;
+    }): Promise<{
+        cancelToken: string;
+        deleteAfter: number;
+    }>;
+    cancelDeletion(token: string): Promise<void>;
+    purgeDeleted(options?: {
+        limit?: number;
+    }): Promise<{
+        purged: number;
+    }>;
+    issueEmailCode(input: {
+        email: string;
+    }): Promise<{
+        flowId: string;
+        code: string | null;
+    }>;
+    consumeEmailCode(input: {
+        trustedDevice?: string;
+        flowId: string;
+        code: string;
+        device?: AuthDevice;
+        totp?: string;
+        recoveryCode?: string;
+        secondFactor?: AuthSecondFactor;
+    }): Promise<AuthSessionResult>;
+    createCase(input: {
+        actorToken: string;
+        accountId: string;
+        action: Exclude<AuthCase['action'], 'restore-access'>;
+        roles?: string[];
+        reason: string;
+    }): Promise<AuthCase>;
+    listCases(options?: {
+        limit?: number;
+        after?: string;
+    }): Promise<{
+        cases: AuthCase[];
+        next?: string;
+    }>;
+    getCase(id: string): Promise<AuthCase | null>;
+    approveCase(input: {
+        actorToken: string;
+        caseId: string;
+        reason: string;
+    }): Promise<AuthCase>;
+    createImpersonation(input: {
+        actorToken: string;
+        accountId: string;
+        reason: string;
+    }): Promise<AuthSessionResult>;
+    adminBulk(input: {
+        actorToken: string;
+        accountIds: string[];
+        action: 'lock' | 'unlock' | 'revoke-sessions';
+        reason: string;
+    }): Promise<{
+        affected: number;
+    }>;
+    dashboard(): Promise<{
+        users: number;
+        active: number;
+        locked: number;
+        pendingDeletion: number;
+        sessions: number;
+        waitlist: number;
+        daily: AuthDailyMetric[];
+    }>;
+    listAllSessions(options?: {
+        accountId?: string;
+        device?: string;
+        createdFrom?: number;
+        createdTo?: number;
+        limit?: number;
+        after?: string;
+    }): Promise<{
+        sessions: (AuthSession & {
+            accountId: string;
+            email: string;
+        })[];
+        next?: string;
+    }>;
+    importUsers(users: {
+        email: string;
+        passwordHash: string;
+        emailVerified?: boolean;
+    }[]): Promise<{
+        imported: number;
+    }>;
+    getProfile(token: string): Promise<RegistrationProfile>;
+    updateProfile(input: {
+        token: string;
+        profile: RegistrationInput;
+    }): Promise<RegistrationProfile>;
+    getConfigurationRevision(): Promise<string>;
+    getSecurityPolicy(): AuthSecurityPolicy;
+    getHookStats(): AuthHookStats;
+    getRegistrationSchema(): RegistrationOptions;
+    getRegistrationMode(): 'open' | 'invite-only' | 'waitlist' | 'off';
+    requestRegistration(input: {
+        email: string;
+        password: string;
+        profile?: RegistrationInput;
+    }): Promise<{
+        id: string;
+    }>;
+    listRegistrationRequests(options?: {
+        limit?: number;
+        after?: string;
+    }): Promise<{
+        requests: {
+            id: string;
+            email: string;
+            created: number;
+        }[];
+        next?: string;
+    }>;
+    approveRegistration(input: {
+        actorToken: string;
+        requestId: string;
+        reason?: string;
+    }): Promise<AuthUser>;
+    invite(input: {
+        actorToken: string;
+        email: string;
+    }): Promise<{
+        token: string;
+    }>;
+    completeStepUp(input: {
+        token: string;
+        accountId: string;
+        method: 'passkey';
+        proof: PasskeyAuthProof;
+        totp?: string;
+        recoveryCode?: string;
+        secondFactor?: AuthSecondFactor;
+    }): Promise<AuthSessionResult>;
+    removePasskey(input: {
+        token: string;
+        credentialId: string;
+    }): Promise<void>;
+    unlinkExternal(input: {
+        token: string;
+        provider: string;
+        subject: string;
+    }): Promise<void>;
+    closeCase(input: {
+        actorToken: string;
+        caseId: string;
+        reason: string;
+    }): Promise<AuthCase>;
+    addCaseNote(input: {
+        actorToken: string;
+        caseId: string;
+        note: string;
+    }): Promise<AuthCase>;
+    cleanup(options?: {
+        limit?: number;
+    }): Promise<{
+        removed: number;
+    }>;
+    requestEmailChange(input: {
+        token: string;
+        email: string;
+        password?: string;
+        totp?: string;
+        recoveryCode?: string;
+        secondFactor?: AuthSecondFactor;
+    }): Promise<{
+        oldEmail: string;
+        newEmail: string;
+        verificationToken: string;
+        cancelToken: string;
+        activateAfter: number;
+    }>;
+    confirmEmailChange(token: string): Promise<AuthUser>;
+    cancelEmailChange(token: string): Promise<void>;
+    adminCreateUser(input: {
+        actorToken: string;
+        email: string;
+        reason: string;
+    }): Promise<{
+        user: AuthUser;
+        setupToken: string;
+    }>;
+    revokeSession(input: {
+        token: string;
+        sessionId: string;
+    }): Promise<void>;
+    adminRevokeSession(input: {
+        actorToken: string;
+        sessionId: string;
+        reason: string;
+    }): Promise<void>;
+    adminAddNote(input: {
+        actorToken: string;
+        accountId: string;
+        reason: string;
+    }): Promise<void>;
+    adminReveal(input: {
+        actorToken: string;
+        accountId: string;
+        reason: string;
+    }): Promise<{
+        id: string;
+        email: string;
+    }>;
+    adminExport(input: {
+        actorToken: string;
+        accountId: string;
+        reason: string;
+    }): Promise<{
+        user: AuthUser;
+        sessions: AuthSession[];
+        identities: {
+            provider: string;
+            subject: string;
+        }[];
+    }>;
+    rotateEncryptionKey(): Promise<{
+        changed: number;
+        remaining: number;
+    }>;
+    close(): Promise<void>;
+}
+export declare function normalizeEmail(value: string): string;
+export declare function createAuthService(options: AuthOptions): Promise<AuthService>;