@yielded/auth-persistence 0.1.0-beta.7

package/src/drizzle/standalone-guard.ts

@@ -0,0 +1,38 @@
+import { Context, Effect, Option, Predicate } from "effect";
+import type * as SqlClient from "effect/unstable/sql/SqlClient";
+
+type TransactionService = Context.Key<
+  SqlClient.TransactionConnection,
+  SqlClient.TransactionConnection.Service
+>;
+
+const transactionService = (database: unknown): TransactionService | undefined => {
+  if (
+    !Predicate.hasProperty(database, "$client") ||
+    !Predicate.hasProperty(database.$client, "transactionService") ||
+    !Context.isKey(database.$client.transactionService)
+  ) {
+    return undefined;
+  }
+
+  return database.$client.transactionService;
+};
+
+/** Bind the client-specific transaction marker at foreign adapter construction. */
+export const sqlClientStandaloneGuard = <Failure>(
+  database: unknown,
+  unavailable: () => Failure,
+): Effect.Effect<void, Failure> => {
+  const service = transactionService(database);
+
+  if (service === undefined) return Effect.suspend(() => Effect.fail(unavailable()));
+
+  return Effect.serviceOption(service).pipe(
+    Effect.flatMap(
+      Option.match({
+        onNone: () => Effect.void,
+        onSome: () => Effect.fail(unavailable()),
+      }),
+    ),
+  );
+};

package/src/drizzle/step-up-model.ts

@@ -0,0 +1,128 @@
+import type { SecurityRevision, SessionStepUpIntent } from "@yielded/auth/Sessions";
+import type { InferInsertModel, Table } from "drizzle-orm";
+import type { DateTime, Effect } from "effect";
+
+import type { PersistenceMappingError } from "./model";
+import type {
+  D1SessionClockMapping,
+  SessionAuthorityTables,
+  SessionConstraintClassifier,
+  SessionIdCodec,
+  SignedSessionValidityTables,
+  StatefulSessionTables,
+} from "./session-model";
+
+type ColumnKey<T extends Table> = Extract<keyof T["_"]["columns"], string>;
+
+/** 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;
+    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 },
+    ) => InferInsertModel<Intent>;
+    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)",
+};
+
+/** Fixed source discriminator is checked against every stored intent. A minimal
+ * pure-signed installation does not provide dummy session or tombstone tables. */
+export type SessionStepUpSourceTables<
+  Claims,
+  Session extends Table,
+  Tombstone extends Table,
+  NativeSubjectId,
+  NativeSessionId,
+> =
+  | { readonly kind: "StatelessSigned" }
+  | ({
+      readonly kind: "StateAssistedSigned";
+      readonly constraints: {
+        readonly tombstoneOwner: "unique(tombstone.subjectId,tombstone.sessionId)";
+      };
+    } & SignedSessionValidityTables<Tombstone, NativeSubjectId, NativeSessionId>)
+  | {
+      readonly kind: "Stateful";
+      readonly constraints: { readonly sessionDigest: "unique(session.digest)" };
+      readonly sessionId: SessionIdCodec<NativeSessionId>;
+      readonly session: StatefulSessionTables<
+        Claims,
+        Session,
+        Table,
+        NativeSubjectId,
+        NativeSessionId
+      >["session"] & {
+        readonly credentialVersion: ColumnKey<Session>;
+        readonly authenticatedAt: ColumnKey<Session>;
+        /** encodeRotation must persist the full replacement Claims/provenance and
+         * these queryable security fields, never preserve the old proof payload. */
+      };
+    };
+
+export type SessionStepUpMapping<
+  Claims,
+  Subject extends Table,
+  Credential extends Table,
+  Intent extends Table,
+  Session extends Table,
+  Tombstone extends Table,
+  NativeSubjectId,
+  NativeSessionId,
+> = SessionAuthorityTables<Subject, Credential, NativeSubjectId> &
+  SessionStepUpIntentTables<Intent, NativeSubjectId> &
+  SessionConstraintClassifier & {
+    readonly source: SessionStepUpSourceTables<
+      Claims,
+      Session,
+      Tombstone,
+      NativeSubjectId,
+      NativeSessionId
+    >;
+    readonly constraints: RequiredSessionStepUpConstraints;
+  };
+
+export type D1SessionStepUpMapping<
+  Claims,
+  Subject extends Table,
+  Credential extends Table,
+  Intent extends Table,
+  Session extends Table,
+  Tombstone extends Table,
+  NativeSubjectId,
+  NativeSessionId,
+> = SessionStepUpMapping<
+  Claims,
+  Subject,
+  Credential,
+  Intent,
+  Session,
+  Tombstone,
+  NativeSubjectId,
+  NativeSessionId
+> &
+  D1SessionClockMapping;

package/src/drizzle/step-up-state.ts

@@ -0,0 +1,139 @@
+import {
+  SessionStepUpInvalid,
+  SessionUnavailable,
+  AuthenticationEvidence,
+  type AuthenticationRevision,
+  SessionMetadata,
+  SessionStepUpIntent,
+  SessionStepUpRequirement,
+  type SessionStepUpCompletionPlan,
+  type StatefulSessionRecord,
+} from "@yielded/auth/Sessions";
+import { DateTime, Effect, Schema } from "effect";
+
+export const stepUpIntentCodec = Schema.fromJsonString(SessionStepUpIntent);
+const BoundedSnapshot = Schema.String.check(Schema.isMaxLength(131072));
+
+export const encodeStepUpIntent = (intent: SessionStepUpIntent) =>
+  Schema.encodeEffect(stepUpIntentCodec)(intent).pipe(
+    Effect.flatMap(Schema.decodeEffect(BoundedSnapshot)),
+    Effect.mapError(() => SessionUnavailable.make({})),
+  );
+
+export const decodeStepUpIntent = (snapshot: string) =>
+  Schema.decodeEffect(BoundedSnapshot)(snapshot).pipe(
+    Effect.flatMap(Schema.decodeEffect(stepUpIntentCodec)),
+    Effect.mapError(() => SessionUnavailable.make({})),
+  );
+
+export const sameStepUpRevision = (left: AuthenticationRevision, right: AuthenticationRevision) =>
+  left.subjectId === right.subjectId &&
+  left.securityRevision === right.securityRevision &&
+  left.credentials.length === right.credentials.length &&
+  new Set(left.credentials.map((c) => c.credentialId)).size === left.credentials.length &&
+  left.credentials.every((item) =>
+    right.credentials.some(
+      (other) => item.credentialId === other.credentialId && item.revision === other.revision,
+    ),
+  );
+
+export const stepUpIntentLive = (
+  intent: SessionStepUpIntent,
+  kind: SessionStepUpIntent["sourceKind"],
+  now: DateTime.Utc,
+) => {
+  const n = DateTime.toEpochMillis(now),
+    authenticated = DateTime.toEpochMillis(intent.sourceAuthenticatedAt),
+    idle = DateTime.toEpochMillis(intent.sourceExpiresAt),
+    absolute = DateTime.toEpochMillis(intent.sourceAbsoluteExpiresAt),
+    expires = DateTime.toEpochMillis(intent.expiresAt);
+
+  return (
+    intent.sourceKind === kind &&
+    authenticated <= n &&
+    n < expires &&
+    expires <= idle &&
+    idle <= absolute
+  );
+};
+
+const evidenceEncoding = Schema.encodeSync(Schema.fromJsonString(AuthenticationEvidence));
+const requirementEncoding = Schema.encodeSync(Schema.fromJsonString(SessionStepUpRequirement));
+const metadataEncoding = Schema.encodeSync(Schema.fromJsonString(SessionMetadata));
+
+/** Validate core-owned plans before driver allocation/SQL expansion. No bearer or Claims decoding. */
+export const validateStepUpPlan = Effect.fn("DrizzleStepUp.validatePlan")(function* <Claims>(
+  plan: SessionStepUpCompletionPlan<Claims>,
+) {
+  const { intent, source, replacement, evidence } = plan;
+  const original = source.inspection;
+
+  if (
+    requirementEncoding(plan.profileRequirement) !== requirementEncoding(intent.requirement) ||
+    replacement.inspection.session.subjectId !== evidence.revision.subjectId ||
+    replacement.inspection.session.securityRevision !== evidence.revision.securityRevision ||
+    intent.revision.credentials.some(
+      (item) =>
+        !evidence.revision.credentials.some(
+          (actual) =>
+            actual.credentialId === item.credentialId && actual.revision === item.revision,
+        ),
+    )
+  )
+    return yield* SessionStepUpInvalid.make({});
+  if (
+    intent.sourceKind !== source.guard._tag ||
+    intent.sourceKind !== replacement._tag ||
+    intent.sourceSessionId !== original.session.sessionId ||
+    intent.sourceCredentialVersion !== original.credentialVersion ||
+    !sameStepUpRevision(intent.revision, original.provenance.evidence.revision) ||
+    intent.revision.subjectId !== evidence.revision.subjectId ||
+    intent.revision.securityRevision !== evidence.revision.securityRevision ||
+    intent.flowId !== evidence.flowId ||
+    intent.bindingDigest !== evidence.bindingDigest ||
+    DateTime.toEpochMillis(intent.sourceAuthenticatedAt) !==
+      DateTime.toEpochMillis(original.session.assurance.authenticatedAt) ||
+    DateTime.toEpochMillis(intent.sourceExpiresAt) !==
+      DateTime.toEpochMillis(original.session.expiresAt) ||
+    DateTime.toEpochMillis(intent.sourceAbsoluteExpiresAt) !==
+      DateTime.toEpochMillis(original.session.absoluteExpiresAt) ||
+    DateTime.toEpochMillis(intent.sourceAuthenticatedAt) !==
+      DateTime.toEpochMillis(replacement.inspection.session.assurance.authenticatedAt) ||
+    DateTime.toEpochMillis(intent.sourceAbsoluteExpiresAt) !==
+      DateTime.toEpochMillis(replacement.inspection.session.absoluteExpiresAt) ||
+    evidenceEncoding(replacement.inspection.provenance.evidence) !== evidenceEncoding(evidence)
+  )
+    return yield* SessionStepUpInvalid.make({});
+  if (
+    replacement._tag === "Stateful" &&
+    (source.guard._tag !== "Stateful" ||
+      source.guard.digest !== replacement.expectedDigest ||
+      source.guard.rowVersion !== replacement.expectedRowVersion ||
+      replacement.inspection.session.sessionId !== intent.sourceSessionId)
+  )
+    return yield* SessionStepUpInvalid.make({});
+  if (
+    replacement._tag === "StateAssistedSigned" &&
+    (replacement.tombstoneSessionId !== intent.sourceSessionId ||
+      DateTime.toEpochMillis(replacement.tombstoneUntil) !==
+        DateTime.toEpochMillis(intent.sourceAbsoluteExpiresAt))
+  )
+    return yield* SessionStepUpInvalid.make({});
+  if (
+    replacement._tag !== "Stateful" &&
+    replacement.inspection.session.sessionId === intent.sourceSessionId
+  )
+    return yield* SessionStepUpInvalid.make({});
+});
+
+/** Compare a consumer-decoded encoded update/readback with the intended rotation.
+ * Claims are consumer-owned; their lossless round trip remains the codec contract. */
+export const stepUpRotationMatches = <Claims>(
+  plan: SessionStepUpCompletionPlan<Claims>,
+  record: StatefulSessionRecord<Claims>,
+) =>
+  plan.replacement._tag === "Stateful" &&
+  record.digest === plan.replacement.nextDigest &&
+  record.credentialVersion === plan.replacement.inspection.credentialVersion &&
+  metadataEncoding(record) === metadataEncoding(plan.replacement.inspection.session) &&
+  evidenceEncoding(record.provenance.evidence) === evidenceEncoding(plan.evidence);

package/src/drizzle/totp-model.ts

@@ -0,0 +1,92 @@
+import type { SubjectId } from "@yielded/auth/Schema";
+import type {
+  AuthenticationRequirement,
+  PendingAuthenticationContext,
+} from "@yielded/auth/Sessions";
+import { type TotpPolicy, TotpPersistence } from "@yielded/auth/Totp";
+import type { InferInsertModel, InferSelectModel, SQL, Table } from "drizzle-orm";
+import { Effect, Layer } from "effect";
+
+import type { PersistenceMappingError } from "./model";
+export type TotpColumn<T extends Table> = Extract<keyof T["_"]["columns"], string>;
+export type TotpMappingSource<M, R = never> = M | Effect.Effect<M, PersistenceMappingError, R>;
+
+export const requiredTotpConstraints = {
+  factor: "unique(scope)",
+  credential: "unique(credentialId)",
+  subject: "unique(id)",
+} as const;
+
+/** A dedicated encrypted factor row plus the shared authentication credential authority.
+ * factorEnabled is the consumer's TOTP requirement bit; central primary methods must
+ * read it when choosing their AuthenticationRequirement. Other factor policy is untouched.
+ * State JSON stores ciphertext and recovery digests only. The same table retains
+ * domain-separated management command tombstones; retain them while command IDs
+ * can be replayed. Encoders and current requirement decoding cannot suspend.
+ */
+export interface TotpMapping<S extends Table, F extends Table, C extends Table, N> {
+  readonly moduleId: string;
+  readonly policy: TotpPolicy;
+  readonly constraints: typeof requiredTotpConstraints;
+  readonly subjectIds: {
+    readonly toNative: (id: SubjectId) => N;
+    readonly toSubject: (id: N) => SubjectId;
+  };
+  readonly subject: {
+    readonly table: S;
+    readonly id: TotpColumn<S>;
+    readonly securityRevision: TotpColumn<S>;
+    readonly factorEnabled: TotpColumn<S>;
+    readonly activeCondition: SQL;
+    readonly encodeEnabled: (enabled: boolean) => unknown;
+    readonly decodeRequirement: (row: InferSelectModel<S>) => AuthenticationRequirement;
+  };
+  readonly factor: {
+    readonly table: F;
+    readonly scope: TotpColumn<F>;
+    readonly state: TotpColumn<F>;
+    readonly version: TotpColumn<F>;
+    readonly encodeInsert: (value: {
+      readonly scope: string;
+      readonly state: string;
+      readonly version: string;
+    }) => InferInsertModel<F>;
+  };
+  readonly credential: {
+    readonly table: C;
+    readonly id: TotpColumn<C>;
+    readonly subjectId: TotpColumn<C>;
+    readonly revision: TotpColumn<C>;
+    readonly status: TotpColumn<C>;
+    readonly activeCondition: SQL;
+    readonly encodeStatus: (active: boolean) => unknown;
+    readonly encodeInsert: (value: {
+      readonly credentialId: string;
+      readonly subjectId: N;
+      readonly revision: string;
+      readonly active: boolean;
+    }) => InferInsertModel<C>;
+  };
+  /** Unix epoch milliseconds, evaluated again at the final conditional write. */
+  readonly engineNowMillis: SQL;
+  /** Required for reset-with-recovery-code. Must assert the exact unconsumed,
+   * unexpired, unexhausted pending flow, binding digest and original credential
+   * revisions. No request-supplied SQL or external I/O is accepted. */
+  readonly pendingCondition?: (target: PendingAuthenticationContext, subjectId: N) => SQL;
+}
+
+export interface D1TotpMapping {
+  readonly d1: { readonly primary: true };
+}
+
+export interface TotpPersistenceServices {
+  readonly totpPersistence: TotpPersistence["Service"];
+}
+
+export const totpPersistenceLayer = <E, R>(
+  services: Effect.Effect<TotpPersistenceServices, E, R>,
+) =>
+  Layer.effect(
+    TotpPersistence,
+    Effect.map(services, (value) => value.totpPersistence),
+  );