@yielded/auth-persistence 0.1.0-beta.25 → 0.1.0-beta.26

package/src/internal/models/session-model.ts

@@ -1,17 +1,17 @@
 import type { TokenDigest } from "@yielded/auth/Schema";
-import {
-  type AuthenticationRequirement,
-  type AuthenticationEvidence,
-  type SecurityRevision,
-  type SessionId,
-  type PendingAuthenticationRecord,
-  type PendingAuthenticationState,
-  type StatefulSessionRecord,
+import type {
+  AuthenticationRequirement,
+  SecurityRevision,
+  SessionId,
+  AuthenticationFlowId,
+  PendingAuthenticationRecord,
+  StatefulSessionRecord,
 } from "@yielded/auth/Sessions";
 import type { DateTime, Effect } from "effect";
 
-import type { TableModel as Table, SqlExpression } from "../query-operations";
+import type { TableModel as Table, SqlExpression } from "../table-model";
 import type { PersistenceMappingError, SubjectIdCodec } from "./common";
+import type { ProofClock } from "./proof-model";
 
 type ColumnKey<T extends Table> = T["column"];
 
@@ -27,10 +27,14 @@ export interface SessionSubjectTables<Subject extends Table, NativeId> {
     readonly id: ColumnKey<Subject>;
     readonly status: ColumnKey<Subject>;
     readonly securityRevision: ColumnKey<Subject>;
+    readonly activeStatusValue: unknown;
     readonly isActiveStatus: (value: unknown) => boolean;
     readonly decodeRequirement: (
       row: Subject["select"],
     ) => Effect.Effect<AuthenticationRequirement, PersistenceMappingError>;
+    /** Required for D1 authority writes. Declare every mutable subject input of
+     * decodeRequirement; [] explicitly declares a constant requirement. */
+    readonly requirementColumns?: ReadonlyArray<ColumnKey<Subject>>;
     readonly nextSecurityRevision?: (
       current: SecurityRevision,
     ) => Effect.Effect<SecurityRevision, PersistenceMappingError>;
@@ -49,53 +53,34 @@ export interface SessionAuthorityTables<
     readonly subjectId: ColumnKey<Credential>;
     readonly credentialId: ColumnKey<Credential>;
     readonly revision: ColumnKey<Credential>;
-    /** Optional consumer status predicate; omitted means every stored credential row is active. */
+    /** Omitted status means every row is an active credential. */
     readonly status?: ColumnKey<Credential>;
+    readonly activeStatusValue?: unknown;
     readonly isActiveStatus?: (value: unknown) => boolean;
   };
 }
 
-export interface SessionFlowTables<Flow extends Table, NativeSubjectId> {
-  readonly flow: {
-    readonly table: Flow["table"];
-    readonly flowId: ColumnKey<Flow>;
-    readonly subjectId: ColumnKey<Flow>;
-    readonly state: ColumnKey<Flow>;
-    readonly pendingDigest: ColumnKey<Flow>;
-    readonly dedupUntil: ColumnKey<Flow>;
-    readonly pendingStateValue: unknown;
-    readonly establishedStateValue: unknown;
-    readonly encodeInstant: (instant: DateTime.Utc) => unknown;
-    readonly decodeInstant: (
-      native: unknown,
-    ) => Effect.Effect<DateTime.Utc, PersistenceMappingError>;
-    readonly encodePendingInsert: (input: {
-      readonly evidence: AuthenticationEvidence;
-      readonly subjectId: NativeSubjectId;
-      readonly pendingDigest: TokenDigest;
-      readonly dedupUntil: DateTime.Utc;
-    }) => Flow["insert"];
-    readonly encodeEstablishedInsert: (input: {
-      readonly evidence: AuthenticationEvidence;
-      readonly subjectId: NativeSubjectId;
-      readonly dedupUntil: DateTime.Utc;
-    }) => Flow["insert"];
-  };
+export interface SessionExecution<Expression extends SqlExpression = SqlExpression> {
+  /** Exact session module scope for pending rows and revocation tombstones. */
+  readonly moduleId: string;
+  readonly clock: ProofClock<Expression>;
+  /** D1 mappings must use the authoritative primary database. */
+  readonly d1?: { readonly primary: true };
+  /** Match only the declared unique keys, never generic SQL failures. */
+  readonly isConstraintConflict: (cause: unknown) => boolean;
 }
 
 export interface StatefulSessionTables<
   Claims,
   Session extends Table,
-  Flow extends Table,
   NativeSubjectId,
   NativeSessionId,
-> extends SessionFlowTables<Flow, NativeSubjectId> {
+> {
   readonly session: {
     readonly table: Session["table"];
     readonly sessionId: ColumnKey<Session>;
     readonly subjectId: ColumnKey<Session>;
     readonly digest: ColumnKey<Session>;
-    readonly version: ColumnKey<Session>;
     readonly securityRevision: ColumnKey<Session>;
     readonly issuedAt: ColumnKey<Session>;
     readonly expiresAt: ColumnKey<Session>;
@@ -103,60 +88,69 @@ export interface StatefulSessionTables<
     readonly encodeInstant: (instant: DateTime.Utc) => unknown;
     readonly encodeInsert: (
       record: StatefulSessionRecord<Claims>,
-      ids: {
-        readonly subjectId: NativeSubjectId;
-        readonly sessionId: NativeSessionId;
-      },
+      ids: { readonly subjectId: NativeSubjectId; readonly sessionId: NativeSessionId },
     ) => Session["insert"];
-    /** Persist the prepared credentialVersion and retain exact private provenance. */
+    /** Replace prepared metadata and retain exact private provenance. Digest binds the immutable source metadata. */
     readonly encodeRotation: (record: StatefulSessionRecord<Claims>) => Partial<Session["insert"]>;
     readonly decode: (
       row: Session["select"],
     ) => Effect.Effect<StatefulSessionRecord<Claims>, PersistenceMappingError>;
     readonly allocateId?: Effect.Effect<NativeSessionId, PersistenceMappingError>;
     readonly allocateIdSync?: () => NativeSessionId;
-    readonly allocateVersion?: Effect.Effect<SecurityRevision, PersistenceMappingError>;
-    readonly allocateVersionSync?: () => SecurityRevision;
   };
   readonly sessionId: SessionIdCodec<NativeSessionId>;
 }
 
-export interface PendingAuthenticationTables<
-  Claims,
-  Pending extends Table,
-  Flow extends Table,
-  NativeSubjectId,
-> extends SessionFlowTables<Flow, NativeSubjectId> {
+export interface SessionPendingInsert<NativeId> {
+  readonly moduleId: string;
+  readonly kind: "Login" | "StepUp";
+  readonly digest: TokenDigest;
+  readonly version: SecurityRevision;
+  readonly flowId: AuthenticationFlowId;
+  readonly subjectId: NativeId;
+  readonly bindingDigest: TokenDigest;
+  readonly snapshot: string;
+  readonly expiresAt: DateTime.Utc;
+  readonly attemptLimit: number;
+}
+
+/** One physical table and one SQL owner for Login and StepUp. The adapter sets
+ * every guard column and binds kind before decoding, charging or consuming. */
+export interface SessionPendingTables<Pending extends Table, NativeSubjectId> {
   readonly pending: {
     readonly table: Pending["table"];
+    readonly moduleId: ColumnKey<Pending>;
+    readonly kind: ColumnKey<Pending>;
     readonly digest: ColumnKey<Pending>;
     readonly version: ColumnKey<Pending>;
     readonly flowId: ColumnKey<Pending>;
     readonly subjectId: ColumnKey<Pending>;
     readonly bindingDigest: ColumnKey<Pending>;
+    readonly snapshot: ColumnKey<Pending>;
     readonly expiresAt: ColumnKey<Pending>;
     readonly attemptLimit: ColumnKey<Pending>;
     readonly failedAttempts: ColumnKey<Pending>;
     readonly consumed: ColumnKey<Pending>;
     readonly encodeInstant: (instant: DateTime.Utc) => unknown;
-    readonly encodeInsert: (
+    readonly encodeInsert: (input: SessionPendingInsert<NativeSubjectId>) => Pending["insert"];
+    readonly allocateVersion?: Effect.Effect<SecurityRevision, PersistenceMappingError>;
+    readonly allocateVersionSync?: () => SecurityRevision;
+  };
+}
+
+export interface PendingAuthenticationTables<
+  Claims,
+  Pending extends Table,
+  NativeSubjectId,
+> extends SessionPendingTables<Pending, NativeSubjectId> {
+  /** Canonical JSON of the full record; the consumer Schema owns Claims encoding. */
+  readonly login: {
+    readonly encode: (
       record: PendingAuthenticationRecord<Claims>,
-      input: {
-        readonly subjectId: NativeSubjectId;
-        readonly failedAttempts: 0;
-        readonly consumed: false;
-      },
-    ) => Pending["insert"];
+    ) => Effect.Effect<string, PersistenceMappingError>;
     readonly decode: (
-      row: Pending["select"],
+      snapshot: unknown,
     ) => Effect.Effect<PendingAuthenticationRecord<Claims>, PersistenceMappingError>;
-    /** Decodes original evidence and storage guards only. The internal pending
-     * context lookup must not execute unrelated consumer Claims transforms. */
-    readonly decodeContext: (
-      row: Pending["select"],
-    ) => Effect.Effect<PendingAuthenticationState, PersistenceMappingError>;
-    readonly allocateVersion?: Effect.Effect<SecurityRevision, PersistenceMappingError>;
-    readonly allocateVersionSync?: () => SecurityRevision;
   };
 }
 
@@ -167,6 +161,7 @@ export interface SignedSessionValidityTables<
 > {
   readonly tombstone: {
     readonly table: Tombstone["table"];
+    readonly moduleId: ColumnKey<Tombstone>;
     readonly subjectId: ColumnKey<Tombstone>;
     readonly sessionId: ColumnKey<Tombstone>;
     readonly absoluteExpiresAt: ColumnKey<Tombstone>;
@@ -175,6 +170,7 @@ export interface SignedSessionValidityTables<
       native: unknown,
     ) => Effect.Effect<DateTime.Utc, PersistenceMappingError>;
     readonly encodeInsert: (input: {
+      readonly moduleId: string;
       readonly subjectId: NativeSubjectId;
       readonly sessionId: NativeSessionId;
       readonly absoluteExpiresAt: DateTime.Utc;
@@ -183,69 +179,42 @@ export interface SignedSessionValidityTables<
   readonly sessionId: SessionIdCodec<NativeSessionId>;
 }
 
-export interface RequiredSessionConstraints {
-  readonly sessionDigest: "unique(session.digest)";
-  readonly flowId: "unique(flow.flowId)";
-}
-
-export interface RequiredPendingAuthenticationConstraints {
-  readonly pendingDigest: "unique(pending.digest)";
-  readonly pendingFlow: "unique(pending.flowId)";
-  readonly flowId: "unique(flow.flowId)";
-}
+export const requiredSessionConstraints = { sessionDigest: "unique(session.digest)" } as const;
 
-export interface RequiredStatefulPendingConstraints
-  extends RequiredSessionConstraints, RequiredPendingAuthenticationConstraints {}
-
-export interface RequiredSignedValidityConstraints {
-  readonly tombstoneOwner: "unique(tombstone.subjectId,tombstone.sessionId)";
-}
-
-export const requiredSessionConstraints: RequiredSessionConstraints = {
-  sessionDigest: "unique(session.digest)",
-  flowId: "unique(flow.flowId)",
-};
-
-export const requiredPendingAuthenticationConstraints: RequiredPendingAuthenticationConstraints = {
+export const requiredPendingAuthenticationConstraints = {
   pendingDigest: "unique(pending.digest)",
-  pendingFlow: "unique(pending.flowId)",
-  flowId: "unique(flow.flowId)",
-};
+} as const;
 
-export const requiredStatefulPendingConstraints: RequiredStatefulPendingConstraints = {
+export const requiredStatefulPendingConstraints = {
   ...requiredSessionConstraints,
   ...requiredPendingAuthenticationConstraints,
-};
+} as const;
 
-export const requiredSignedValidityConstraints: RequiredSignedValidityConstraints = {
-  tombstoneOwner: "unique(tombstone.subjectId,tombstone.sessionId)",
-};
+export const requiredSignedValidityConstraints = {
+  tombstoneOwner: "unique(tombstone.moduleId,tombstone.subjectId,tombstone.sessionId)",
+} as const;
 
-export interface SessionConstraintClassifier {
-  /**
-   * Match only the named unique constraints declared by this mapping. Broad
-   * SQL/constraint classifiers can relabel application or NOT NULL failures as
-   * a domain conflict.
-   */
-  readonly isConstraintConflict: (cause: unknown) => boolean;
-}
+export type RequiredSessionConstraints = typeof requiredSessionConstraints;
+
+export type RequiredPendingAuthenticationConstraints =
+  typeof requiredPendingAuthenticationConstraints;
+
+export type RequiredStatefulPendingConstraints = typeof requiredStatefulPendingConstraints;
+export type RequiredSignedValidityConstraints = typeof requiredSignedValidityConstraints;
 
 export type AuthenticationAuthorityMapping<
   Claims,
   Subject extends Table,
   Credential extends Table,
-  Flow extends Table,
   Pending extends Table,
   NativeSubjectId,
+  Expression extends SqlExpression = SqlExpression,
 > = SessionAuthorityTables<Subject, Credential, NativeSubjectId> &
-  SessionConstraintClassifier &
+  SessionExecution<Expression> &
   (
+    | { readonly pending?: undefined }
     | {
-        /** Omit for single-factor authority installations. Pending input then fails closed. */
-        readonly pending?: undefined;
-      }
-    | {
-        readonly pending: PendingAuthenticationTables<Claims, Pending, Flow, NativeSubjectId>;
+        readonly pending: PendingAuthenticationTables<Claims, Pending, NativeSubjectId>;
         readonly constraints: RequiredPendingAuthenticationConstraints;
       }
   );
@@ -255,26 +224,17 @@ export type StatefulSessionMapping<
   Subject extends Table,
   Credential extends Table,
   Session extends Table,
-  Flow extends Table,
   Pending extends Table,
   NativeSubjectId,
   NativeSessionId,
+  Expression extends SqlExpression = SqlExpression,
 > = SessionAuthorityTables<Subject, Credential, NativeSubjectId> &
-  StatefulSessionTables<Claims, Session, Flow, NativeSubjectId, NativeSessionId> &
-  SessionConstraintClassifier &
+  StatefulSessionTables<Claims, Session, NativeSubjectId, NativeSessionId> &
+  SessionExecution<Expression> &
   (
+    | { readonly pending?: undefined; readonly constraints: RequiredSessionConstraints }
     | {
-        /** Omit when this session module does not support pending MFA completion. */
-        readonly pending?: undefined;
-        readonly constraints: RequiredSessionConstraints;
-      }
-    | {
-        readonly pending: PendingAuthenticationTables<
-          Claims,
-          Pending,
-          Flow,
-          NativeSubjectId
-        >["pending"];
+        readonly pending: PendingAuthenticationTables<Claims, Pending, NativeSubjectId>;
         readonly constraints: RequiredStatefulPendingConstraints;
       }
   );
@@ -284,92 +244,34 @@ export type PendingAuthenticationMapping<
   Subject extends Table,
   Credential extends Table,
   Pending extends Table,
-  Flow extends Table,
   NativeSubjectId,
+  Expression extends SqlExpression = SqlExpression,
 > = SessionAuthorityTables<Subject, Credential, NativeSubjectId> &
-  PendingAuthenticationTables<Claims, Pending, Flow, NativeSubjectId> &
-  SessionConstraintClassifier & {
-    readonly constraints: RequiredPendingAuthenticationConstraints;
-  };
+  PendingAuthenticationTables<Claims, Pending, NativeSubjectId> &
+  SessionExecution<Expression> & { readonly constraints: RequiredPendingAuthenticationConstraints };
 
 export type SignedSessionValidityMapping<
   Subject extends Table,
   Tombstone extends Table,
   NativeSubjectId,
   NativeSessionId,
+  Expression extends SqlExpression = SqlExpression,
 > = SessionSubjectTables<Subject, NativeSubjectId> &
   SignedSessionValidityTables<Tombstone, NativeSubjectId, NativeSessionId> &
-  SessionConstraintClassifier & {
-    readonly constraints: RequiredSignedValidityConstraints;
-  };
+  SessionExecution<Expression> & { readonly constraints: RequiredSignedValidityConstraints };
 
-/** D1 evaluates these expressions inside the atomic batch, after queueing delay.
- * `engineNow` must use the exact native representation of every mapped instant
- * column. `engineNowMillis` is Unix epoch milliseconds for proof freshness.
- * Changes to the consumer's factor policy MUST bump subject.securityRevision.
- * Supply the authoritative primary D1 database, never a replica-affined
- * `withSession` handle, because verification and security revision reads must
- * observe completed revocation writes across clients.
- */
-export interface D1SessionClockMapping<Expression extends SqlExpression = SqlExpression> {
-  readonly d1: {
-    readonly engineNow: Expression;
-    readonly engineNowMillis: Expression;
-    readonly activeSubjectStatusValue: unknown;
-    /** Required when `credential.status` is mapped. */
-    readonly activeCredentialStatusValue?: unknown;
-  };
-}
-
-export type D1AuthenticationAuthorityMapping<
-  Claims,
-  Subject extends Table,
-  Credential extends Table,
-  Flow extends Table,
+/** Maintenance uses the same mapped rows and one total per-call deletion limit. */
+export type SessionCleanupMapping<
   Pending extends Table,
-  NativeSubjectId,
-  Expression extends SqlExpression = SqlExpression,
-> = AuthenticationAuthorityMapping<Claims, Subject, Credential, Flow, Pending, NativeSubjectId> &
-  D1SessionClockMapping<Expression>;
-
-export type D1PendingAuthenticationMapping<
-  Claims,
-  Subject extends Table,
-  Credential extends Table,
-  Pending extends Table,
-  Flow extends Table,
-  NativeSubjectId,
-  Expression extends SqlExpression = SqlExpression,
-> = PendingAuthenticationMapping<Claims, Subject, Credential, Pending, Flow, NativeSubjectId> &
-  D1SessionClockMapping<Expression>;
-
-export type D1StatefulSessionMapping<
-  Claims,
-  Subject extends Table,
-  Credential extends Table,
-  Session extends Table,
-  Flow extends Table,
-  Pending extends Table,
-  NativeSubjectId,
-  NativeSessionId,
-  Expression extends SqlExpression = SqlExpression,
-> = StatefulSessionMapping<
-  Claims,
-  Subject,
-  Credential,
-  Session,
-  Flow,
-  Pending,
-  NativeSubjectId,
-  NativeSessionId
-> &
-  D1SessionClockMapping<Expression>;
-
-export type D1SignedSessionValidityMapping<
-  Subject extends Table,
   Tombstone extends Table,
   NativeSubjectId,
   NativeSessionId,
   Expression extends SqlExpression = SqlExpression,
-> = SignedSessionValidityMapping<Subject, Tombstone, NativeSubjectId, NativeSessionId> &
-  D1SessionClockMapping<Expression>;
+> = Pick<SessionExecution<Expression>, "moduleId" | "clock" | "d1"> & {
+  readonly pending?: SessionPendingTables<Pending, NativeSubjectId>["pending"];
+  readonly tombstone?: SignedSessionValidityTables<
+    Tombstone,
+    NativeSubjectId,
+    NativeSessionId
+  >["tombstone"];
+};

package/src/internal/models/step-up-model.ts

@@ -1,59 +1,18 @@
-import type { SecurityRevision, SessionStepUpIntent } from "@yielded/auth/Sessions";
-import type { DateTime, Effect } from "effect";
-
-import type { TableModel as Table, SqlExpression } from "../query-operations";
-import type { PersistenceMappingError } from "./common";
+import type { TableModel as Table, SqlExpression } from "../table-model";
 import type {
-  D1SessionClockMapping,
   SessionAuthorityTables,
-  SessionConstraintClassifier,
-  SessionIdCodec,
+  SessionExecution,
+  SessionPendingTables,
   SignedSessionValidityTables,
   StatefulSessionTables,
 } from "./session-model";
+import { requiredPendingAuthenticationConstraints } from "./session-model";
 
-type ColumnKey<T extends Table> = T["column"];
-
-/** Distinct from login-pending storage. Snapshot is TEXT encoded by the core's
- * SessionStepUpIntent schema; it contains no Claims and needs no consumer decoder. */
-export interface SessionStepUpIntentTables<Intent extends Table, NativeSubjectId> {
-  readonly intent: {
-    readonly table: Intent["table"];
-    readonly digest: ColumnKey<Intent>;
-    readonly version: ColumnKey<Intent>;
-    readonly flowId: ColumnKey<Intent>;
-    readonly subjectId: ColumnKey<Intent>;
-    readonly bindingDigest: ColumnKey<Intent>;
-    readonly snapshot: ColumnKey<Intent>;
-    readonly expiresAt: ColumnKey<Intent>;
-    readonly attemptLimit: ColumnKey<Intent>;
-    readonly failedAttempts: ColumnKey<Intent>;
-    readonly consumed: ColumnKey<Intent>;
-    readonly encodeInstant: (instant: DateTime.Utc) => unknown;
-    /** Consumer fields/defaults; the adapter sets all mapped security columns. */
-    readonly encodeInsert: (
-      intent: SessionStepUpIntent,
-      input: {
-        readonly subjectId: NativeSubjectId;
-      },
-    ) => Intent["insert"];
-    readonly allocateVersion?: Effect.Effect<SecurityRevision, PersistenceMappingError>;
-    readonly allocateVersionSync?: () => SecurityRevision;
-  };
-}
-
-export interface RequiredSessionStepUpConstraints {
-  readonly intentDigest: "unique(intent.digest)";
-  readonly intentFlow: "unique(intent.flowId)";
-}
-
-export const requiredSessionStepUpConstraints: RequiredSessionStepUpConstraints = {
-  intentDigest: "unique(intent.digest)",
-  intentFlow: "unique(intent.flowId)",
-};
+export const requiredSessionStepUpConstraints = requiredPendingAuthenticationConstraints;
+export type RequiredSessionStepUpConstraints = typeof requiredSessionStepUpConstraints;
 
-/** Fixed source discriminator is checked against every stored intent. A minimal
- * pure-signed installation does not provide dummy session or tombstone tables. */
+/** Stateful metadata is decoded from the exact inspected digest's record. No
+ * duplicate credentialVersion/authenticatedAt columns or row-version CAS. */
 export type SessionStepUpSourceTables<
   Claims,
   Session extends Table,
@@ -61,47 +20,31 @@ export type SessionStepUpSourceTables<
   NativeSubjectId,
   NativeSessionId,
 > =
-  | {
-      readonly kind: "StatelessSigned";
-    }
+  | { readonly kind: "StatelessSigned" }
   | ({
       readonly kind: "StateAssistedSigned";
       readonly constraints: {
-        readonly tombstoneOwner: "unique(tombstone.subjectId,tombstone.sessionId)";
+        readonly tombstoneOwner: "unique(tombstone.moduleId,tombstone.subjectId,tombstone.sessionId)";
       };
     } & SignedSessionValidityTables<Tombstone, NativeSubjectId, NativeSessionId>)
-  | {
+  | ({
       readonly kind: "Stateful";
-      readonly constraints: {
-        readonly sessionDigest: "unique(session.digest)";
-      };
-      readonly sessionId: SessionIdCodec<NativeSessionId>;
-      /** encodeRotation must replace Claims, provenance, and the queryable security
-       * fields together; it must not retain the old proof payload. */
-      readonly session: StatefulSessionTables<
-        Claims,
-        Session,
-        Table,
-        NativeSubjectId,
-        NativeSessionId
-      >["session"] & {
-        readonly credentialVersion: ColumnKey<Session>;
-        readonly authenticatedAt: ColumnKey<Session>;
-      };
-    };
+      readonly constraints: { readonly sessionDigest: "unique(session.digest)" };
+    } & StatefulSessionTables<Claims, Session, NativeSubjectId, NativeSessionId>);
 
 export type SessionStepUpMapping<
   Claims,
   Subject extends Table,
   Credential extends Table,
-  Intent extends Table,
+  Pending extends Table,
   Session extends Table,
   Tombstone extends Table,
   NativeSubjectId,
   NativeSessionId,
+  Expression extends SqlExpression = SqlExpression,
 > = SessionAuthorityTables<Subject, Credential, NativeSubjectId> &
-  SessionStepUpIntentTables<Intent, NativeSubjectId> &
-  SessionConstraintClassifier & {
+  SessionPendingTables<Pending, NativeSubjectId> &
+  SessionExecution<Expression> & {
     readonly source: SessionStepUpSourceTables<
       Claims,
       Session,
@@ -111,25 +54,3 @@ export type SessionStepUpMapping<
     >;
     readonly constraints: RequiredSessionStepUpConstraints;
   };
-
-export type D1SessionStepUpMapping<
-  Claims,
-  Subject extends Table,
-  Credential extends Table,
-  Intent extends Table,
-  Session extends Table,
-  Tombstone extends Table,
-  NativeSubjectId,
-  NativeSessionId,
-  Expression extends SqlExpression = SqlExpression,
-> = SessionStepUpMapping<
-  Claims,
-  Subject,
-  Credential,
-  Intent,
-  Session,
-  Tombstone,
-  NativeSubjectId,
-  NativeSessionId
-> &
-  D1SessionClockMapping<Expression>;

package/src/internal/models/totp-model.ts

@@ -0,0 +1,82 @@
+import type { SubjectId } from "@yielded/auth/Schema";
+import type { AuthenticationRequirement } from "@yielded/auth/Sessions";
+import type { TotpPolicy } from "@yielded/auth/Totp";
+import type { Effect } from "effect";
+
+import type { PersistenceMappingError } from "../mapping-error";
+import type { TableModel, SqlExpression } from "../table-model";
+import type { ProofClock } from "./proof-model";
+import type { PendingAuthenticationTables } from "./session-model";
+
+export const requiredTotpConstraints = {
+  factor: "unique(scope)",
+  credential: "unique(credentialId)",
+  subject: "unique(id)",
+} as const;
+
+export type TotpMappingSource<M, R = never> = M | Effect.Effect<M, PersistenceMappingError, R>;
+
+/** One encrypted factor row and the common credential authority. Version protects
+ * accepted-step, failure-budget and recovery-code changes; no command receipts. */
+export interface TotpMapping<
+  S extends TableModel,
+  F extends TableModel,
+  C extends TableModel,
+  N,
+  P extends TableModel = TableModel,
+  Expression extends SqlExpression = SqlExpression,
+> {
+  readonly moduleId: string;
+  readonly policy: TotpPolicy;
+  readonly constraints: typeof requiredTotpConstraints;
+  readonly d1?: { readonly primary: true };
+  readonly subjectIds: {
+    readonly toNative: (id: SubjectId) => N;
+    readonly toSubject: (id: N) => SubjectId;
+  };
+  readonly subject: {
+    readonly table: S["table"];
+    readonly id: S["column"];
+    readonly securityRevision: S["column"];
+    readonly factorEnabled: S["column"];
+    readonly activeCondition: Expression;
+    readonly encodeEnabled: (enabled: boolean) => unknown;
+    readonly decodeRequirement: (row: S["select"]) => AuthenticationRequirement;
+    /** Required for D1: declare every independently mutable input read by
+     * decodeRequirement. An explicit [] promises a constant requirement. */
+    readonly requirementColumns?: ReadonlyArray<S["column"]>;
+  };
+  readonly factor: {
+    readonly table: F["table"];
+    readonly scope: F["column"];
+    readonly state: F["column"];
+    readonly version: F["column"];
+    readonly encodeInsert: (value: {
+      readonly scope: string;
+      readonly state: string;
+      readonly version: string;
+    }) => F["insert"];
+  };
+  readonly credential: {
+    readonly table: C["table"];
+    readonly id: C["column"];
+    readonly subjectId: C["column"];
+    readonly revision: C["column"];
+    readonly status: C["column"];
+    readonly activeCondition: Expression;
+    readonly encodeStatus: (active: boolean) => unknown;
+    readonly encodeInsert: (value: {
+      readonly credentialId: string;
+      readonly subjectId: N;
+      readonly revision: string;
+      readonly active: boolean;
+    }) => C["insert"];
+  };
+  readonly engineNowMillis: Expression;
+  /** Reset uses the very same Login-kind row owner as pending authentication. */
+  readonly pending?: Omit<PendingAuthenticationTables<unknown, P, N>, "login"> & {
+    readonly login: Pick<PendingAuthenticationTables<unknown, P, N>["login"], "decode">;
+    readonly moduleId: string;
+    readonly clock: ProofClock<Expression>;
+  };
+}