@yielded/auth 0.1.0-beta.1

package/src/testing/conformance/OAuthConnectionStore.ts

@@ -0,0 +1,167 @@
+import { DateTime, Duration, Effect, Option, Redacted, Schema } from "effect";
+
+import { OAuthConnectionStore } from "../../oauth/OAuthConnectionStore";
+import { OAuthConnection, OAuthIdentity, OAuthProviderKey, OAuthTokens } from "../../oauth/schema";
+import { check, decodeSubjectId } from "./support";
+
+// Contract checks a downstream (typically encrypting) `OAuthConnectionStore`
+// adapter must pass: keyed round-trips that preserve the redacted token
+// values, replacement on put, removal, and isolation across subjects and
+// providers. Run each case with `it.effect`.
+
+export interface OAuthConnectionStoreConformanceCase {
+  readonly name: string;
+  readonly run: Effect.Effect<void, never, OAuthConnectionStore>;
+}
+
+const decodeOAuthProviderKey = Schema.decodeSync(OAuthProviderKey);
+
+const conformanceProvider = decodeOAuthProviderKey("conformance");
+const otherConformanceProvider = decodeOAuthProviderKey("conformance-other");
+
+const makeOAuthConnection = (options: {
+  readonly provider?: OAuthProviderKey;
+  readonly subject: string;
+  readonly accessToken: string;
+  readonly refreshToken?: string;
+}): Effect.Effect<OAuthConnection> =>
+  Effect.map(DateTime.now, (now) => {
+    const provider = options.provider ?? conformanceProvider;
+
+    return OAuthConnection.make({
+      provider,
+      subjectId: decodeSubjectId(options.subject),
+      identity: OAuthIdentity.make({
+        provider,
+        providerAccountId: `account:${options.subject}`,
+        handle: Option.some(options.subject),
+      }),
+      tokens: OAuthTokens.make({
+        accessToken: Redacted.make(options.accessToken),
+        tokenType: "bearer",
+        accessTokenExpiresAt: Option.some(DateTime.addDuration(now, Duration.hours(8))),
+        refreshToken:
+          options.refreshToken === undefined
+            ? Option.none()
+            : Option.some(Redacted.make(options.refreshToken)),
+        refreshTokenExpiresAt: Option.none(),
+        scope: Option.none(),
+      }),
+      connectedAt: now,
+      updatedAt: now,
+    });
+  });
+
+const oauthConnectionCase = <CaseError>(
+  name: string,
+  run: Effect.Effect<void, CaseError, OAuthConnectionStore>,
+): OAuthConnectionStoreConformanceCase => ({ name, run: Effect.orDie(run) });
+
+export const oauthConnectionStoreConformanceCases: ReadonlyArray<OAuthConnectionStoreConformanceCase> =
+  [
+    oauthConnectionCase(
+      "put and get round-trip the connection including token values",
+      Effect.gen(function* () {
+        const store = yield* OAuthConnectionStore;
+
+        const connection = yield* makeOAuthConnection({
+          subject: "roundtrip",
+          accessToken: "access-roundtrip",
+          refreshToken: "refresh-roundtrip",
+        });
+
+        yield* store.put(connection);
+        const loaded = yield* store.get(conformanceProvider, connection.subjectId);
+
+        yield* check(Option.isSome(loaded), "get must return the stored connection");
+        if (Option.isSome(loaded)) {
+          yield* check(
+            Redacted.value(loaded.value.tokens.accessToken) === "access-roundtrip" &&
+              Option.isSome(loaded.value.tokens.refreshToken) &&
+              Redacted.value(loaded.value.tokens.refreshToken.value) === "refresh-roundtrip",
+            "token values must survive the round-trip exactly",
+          );
+          yield* check(
+            loaded.value.identity.providerAccountId === "account:roundtrip",
+            "the identity must survive the round-trip",
+          );
+        }
+      }),
+    ),
+
+    oauthConnectionCase(
+      "put replaces the existing connection for the same key",
+      Effect.gen(function* () {
+        const store = yield* OAuthConnectionStore;
+
+        yield* store.put(
+          yield* makeOAuthConnection({ subject: "replace", accessToken: "access-before" }),
+        );
+        yield* store.put(
+          yield* makeOAuthConnection({ subject: "replace", accessToken: "access-after" }),
+        );
+        const loaded = yield* store.get(conformanceProvider, decodeSubjectId("replace"));
+
+        yield* check(
+          Option.isSome(loaded) &&
+            Redacted.value(loaded.value.tokens.accessToken) === "access-after",
+          "put must replace the previous connection",
+        );
+      }),
+    ),
+
+    oauthConnectionCase(
+      "remove deletes the connection and is idempotent",
+      Effect.gen(function* () {
+        const store = yield* OAuthConnectionStore;
+        const subjectId = decodeSubjectId("remove");
+
+        yield* store.put(
+          yield* makeOAuthConnection({ subject: "remove", accessToken: "access-remove" }),
+        );
+        yield* store.remove(conformanceProvider, subjectId);
+        const loaded = yield* store.get(conformanceProvider, subjectId);
+
+        yield* check(Option.isNone(loaded), "a removed connection must not be readable");
+        yield* store.remove(conformanceProvider, subjectId);
+      }),
+    ),
+
+    oauthConnectionCase(
+      "connections are isolated by subject and by provider",
+      Effect.gen(function* () {
+        const store = yield* OAuthConnectionStore;
+
+        yield* store.put(
+          yield* makeOAuthConnection({ subject: "isolation-a", accessToken: "access-a" }),
+        );
+        yield* store.put(
+          yield* makeOAuthConnection({ subject: "isolation-b", accessToken: "access-b" }),
+        );
+        yield* store.put(
+          yield* makeOAuthConnection({
+            provider: otherConformanceProvider,
+            subject: "isolation-a",
+            accessToken: "access-a-other",
+          }),
+        );
+        const first = yield* store.get(conformanceProvider, decodeSubjectId("isolation-a"));
+        const second = yield* store.get(conformanceProvider, decodeSubjectId("isolation-b"));
+        const other = yield* store.get(otherConformanceProvider, decodeSubjectId("isolation-a"));
+
+        yield* check(
+          Option.isSome(first) && Redacted.value(first.value.tokens.accessToken) === "access-a",
+          "subject A must read its own connection",
+        );
+        yield* check(
+          Option.isSome(second) && Redacted.value(second.value.tokens.accessToken) === "access-b",
+          "subject B must read its own connection",
+        );
+        yield* check(
+          Option.isSome(other) &&
+            Redacted.value(other.value.tokens.accessToken) === "access-a-other",
+          "the same subject on another provider must read that provider's connection",
+        );
+      }),
+    ),
+  ];

package/src/testing/conformance/OAuthStateStore.ts

@@ -0,0 +1,105 @@
+import { DateTime, Duration, Effect, Schema } from "effect";
+import { TestClock } from "effect/testing";
+
+import { OAuthStateStore } from "../../oauth/OAuthStateStore";
+import { OAuthProviderKey, OAuthState } from "../../oauth/schema";
+import { check, decodeSubjectId, expectFailure, tokenDigestOf } from "./support";
+
+// Pure store-contract checks for `OAuthStateStore` adapters: state digests
+// are opaque strings to the store, so the suite fabricates them directly.
+// Run each case with `it.effect` (TestClock required) against the adapter's
+// layer.
+
+export interface OAuthStateStoreConformanceCase {
+  readonly name: string;
+  readonly run: Effect.Effect<void, never, OAuthStateStore>;
+}
+
+const conformanceProvider = Schema.decodeSync(OAuthProviderKey)("conformance");
+
+const makeOAuthState = (options: {
+  readonly token: string;
+  readonly subject?: string;
+  readonly lifetime?: Duration.Duration;
+}): Effect.Effect<OAuthState> =>
+  Effect.map(DateTime.now, (now) =>
+    OAuthState.make({
+      stateDigest: tokenDigestOf(options.token),
+      provider: conformanceProvider,
+      subjectId: decodeSubjectId(options.subject ?? "conformance-subject"),
+      redirectUri: "https://app.conformance.test/oauth/callback",
+      issuedAt: now,
+      expiresAt: DateTime.addDuration(now, options.lifetime ?? Duration.minutes(10)),
+    }),
+  );
+
+const oauthStateCase = <CaseError>(
+  name: string,
+  run: Effect.Effect<void, CaseError, OAuthStateStore>,
+): OAuthStateStoreConformanceCase => ({ name, run: Effect.orDie(run) });
+
+export const oauthStateStoreConformanceCases: ReadonlyArray<OAuthStateStoreConformanceCase> = [
+  oauthStateCase(
+    "consume returns the issued state exactly once",
+    Effect.gen(function* () {
+      const store = yield* OAuthStateStore;
+
+      yield* store.issue(yield* makeOAuthState({ token: "oauth-once" }));
+      const state = yield* store.consume(tokenDigestOf("oauth-once"));
+
+      yield* check(
+        state.redirectUri === "https://app.conformance.test/oauth/callback",
+        "consume must return the stored state",
+      );
+      yield* expectFailure(
+        store.consume(tokenDigestOf("oauth-once")),
+        "InvalidOAuthState",
+        "a consumed state must reject replays",
+      );
+    }),
+  ),
+
+  oauthStateCase(
+    "parallel consumption produces exactly one success",
+    Effect.gen(function* () {
+      const store = yield* OAuthStateStore;
+
+      yield* store.issue(yield* makeOAuthState({ token: "oauth-parallel" }));
+
+      const exits = yield* Effect.all(
+        Array.from({ length: 8 }, () =>
+          Effect.exit(store.consume(tokenDigestOf("oauth-parallel"))),
+        ),
+        { concurrency: "unbounded" },
+      );
+
+      const successes = exits.filter((exit) => exit._tag === "Success").length;
+
+      yield* check(successes === 1, `expected exactly one success, saw ${successes}`);
+    }),
+  ),
+
+  oauthStateCase(
+    "an expired state is rejected at its expiry instant",
+    Effect.gen(function* () {
+      const store = yield* OAuthStateStore;
+
+      yield* store.issue(yield* makeOAuthState({ token: "oauth-expiry" }));
+      yield* TestClock.adjust(Duration.minutes(10));
+      yield* expectFailure(
+        store.consume(tokenDigestOf("oauth-expiry")),
+        "InvalidOAuthState",
+        "a state must be rejected once its expiry instant is reached",
+      );
+    }),
+  ),
+
+  oauthStateCase(
+    "unknown digests fail with the generic typed error",
+    expectFailure(
+      Effect.flatMap(OAuthStateStore, (store) => store.consume(tokenDigestOf("oauth-unknown"))),
+      "InvalidOAuthState",
+      "an unknown state digest must map to the generic state error",
+    ),
+  ),
+];

package/src/testing/conformance/PasswordCredentialStore.ts

@@ -0,0 +1,205 @@
+import { DateTime, Duration, Effect, Layer, Option, Schema } from "effect";
+import { TestClock } from "effect/testing";
+
+import { IdentityResolver } from "../../IdentityResolver";
+import { PasswordCredentialStore } from "../../PasswordCredentialStore";
+import { type Email, type SubjectId, PasswordHash } from "../../Schema";
+import { check, decodeSubjectId, emailOf } from "./support";
+
+// Pure store-contract checks for `PasswordCredentialStore` adapters: hashes
+// are opaque strings to the store, so the suite fabricates them directly and
+// never needs a hasher. The adapter under test must resolve each conformance
+// email to `credentialConformanceSubject` of that email; adapters that
+// delegate email lookup to `IdentityResolver` (like
+// `PasswordCredentialStore.layerMemory`) can use
+// `layerCredentialConformanceResolver`. Run each case with `it.effect`.
+
+export interface PasswordCredentialStoreConformanceCase {
+  readonly name: string;
+  readonly run: Effect.Effect<void, never, PasswordCredentialStore>;
+}
+
+const decodePasswordHash = Schema.decodeSync(PasswordHash);
+
+/** Subject id the adapter under test must map a conformance email to. */
+export const credentialConformanceSubject = (email: Email): SubjectId =>
+  decodeSubjectId(`subject:${email}`);
+
+/**
+ * `IdentityResolver` implementing the credential-conformance email mapping,
+ * for adapters that resolve emails through the resolver.
+ */
+export const layerCredentialConformanceResolver: Layer.Layer<IdentityResolver> = Layer.succeed(
+  IdentityResolver,
+)({
+  findByVerifiedEmail: (email) => Effect.succeed(Option.some(credentialConformanceSubject(email))),
+});
+
+const passwordHashOf = (name: string) => decodePasswordHash(`password-hash:${name}`);
+
+const credentialLockOptions = { attemptLimit: 3, lockDuration: Duration.minutes(15) };
+
+const credentialCase = <CaseError>(
+  name: string,
+  run: Effect.Effect<void, CaseError, PasswordCredentialStore>,
+): PasswordCredentialStoreConformanceCase => ({ name, run: Effect.orDie(run) });
+
+export const passwordCredentialStoreConformanceCases: ReadonlyArray<PasswordCredentialStoreConformanceCase> =
+  [
+    credentialCase(
+      "upsert and find round-trip through subject and email",
+      Effect.gen(function* () {
+        const store = yield* PasswordCredentialStore;
+        const email = emailOf("credential-roundtrip");
+        const subjectId = credentialConformanceSubject(email);
+
+        yield* store.upsert(subjectId, passwordHashOf("roundtrip"));
+        const bySubject = yield* store.findBySubject(subjectId);
+
+        yield* check(
+          Option.isSome(bySubject) && bySubject.value.hash === passwordHashOf("roundtrip"),
+          "findBySubject must return the upserted hash",
+        );
+        const byEmail = yield* store.findByEmail(email);
+
+        yield* check(
+          Option.isSome(byEmail) && byEmail.value.subjectId === subjectId,
+          "findByEmail must resolve to the same credential",
+        );
+        yield* check(
+          Option.isSome(byEmail) &&
+            byEmail.value.failedAttempts === 0 &&
+            Option.isNone(byEmail.value.lockedUntil),
+          "a fresh credential must be unlocked with zero failures",
+        );
+      }),
+    ),
+
+    credentialCase(
+      "failures count up and lock at the configured threshold",
+      Effect.gen(function* () {
+        const store = yield* PasswordCredentialStore;
+        const email = emailOf("credential-lock");
+        const subjectId = credentialConformanceSubject(email);
+
+        yield* store.upsert(subjectId, passwordHashOf("lock"));
+        yield* store.recordFailure(subjectId, credentialLockOptions);
+        yield* store.recordFailure(subjectId, credentialLockOptions);
+        const beforeLock = yield* store.findByEmail(email);
+
+        yield* check(
+          Option.isSome(beforeLock) &&
+            beforeLock.value.failedAttempts === 2 &&
+            Option.isNone(beforeLock.value.lockedUntil),
+          "failures below the limit must count without locking",
+        );
+        yield* store.recordFailure(subjectId, credentialLockOptions);
+        const locked = yield* store.findByEmail(email);
+        const now = yield* DateTime.now;
+
+        yield* check(
+          Option.isSome(locked) &&
+            locked.value.failedAttempts === 3 &&
+            Option.isSome(locked.value.lockedUntil) &&
+            DateTime.toEpochMillis(locked.value.lockedUntil.value) > DateTime.toEpochMillis(now),
+          "reaching the limit must set a lock in the future",
+        );
+      }),
+    ),
+
+    credentialCase(
+      "success clears failures and the lock without touching the hash",
+      Effect.gen(function* () {
+        const store = yield* PasswordCredentialStore;
+        const email = emailOf("credential-success");
+        const subjectId = credentialConformanceSubject(email);
+
+        yield* store.upsert(subjectId, passwordHashOf("success"));
+        yield* store.recordFailure(subjectId, credentialLockOptions);
+        yield* store.recordFailure(subjectId, credentialLockOptions);
+        yield* store.recordFailure(subjectId, credentialLockOptions);
+        yield* store.recordSuccess(subjectId);
+        const credential = yield* store.findByEmail(email);
+
+        yield* check(
+          Option.isSome(credential) &&
+            credential.value.failedAttempts === 0 &&
+            Option.isNone(credential.value.lockedUntil) &&
+            credential.value.hash === passwordHashOf("success"),
+          "recordSuccess must reset failures and the lock and keep the hash",
+        );
+      }),
+    ),
+
+    credentialCase(
+      "upsert replaces the hash and clears failures and the lock",
+      Effect.gen(function* () {
+        const store = yield* PasswordCredentialStore;
+        const email = emailOf("credential-upsert-reset");
+        const subjectId = credentialConformanceSubject(email);
+
+        yield* store.upsert(subjectId, passwordHashOf("before"));
+        yield* store.recordFailure(subjectId, credentialLockOptions);
+        yield* store.recordFailure(subjectId, credentialLockOptions);
+        yield* store.recordFailure(subjectId, credentialLockOptions);
+        yield* store.upsert(subjectId, passwordHashOf("after"));
+        const credential = yield* store.findByEmail(email);
+
+        yield* check(
+          Option.isSome(credential) &&
+            credential.value.hash === passwordHashOf("after") &&
+            credential.value.failedAttempts === 0 &&
+            Option.isNone(credential.value.lockedUntil),
+          "upsert must replace the hash and reset failures and the lock",
+        );
+      }),
+    ),
+
+    credentialCase(
+      "an expired lock starts a fresh failure window",
+      Effect.gen(function* () {
+        const store = yield* PasswordCredentialStore;
+        const email = emailOf("credential-lock-expiry");
+        const subjectId = credentialConformanceSubject(email);
+
+        yield* store.upsert(subjectId, passwordHashOf("lock-expiry"));
+        yield* store.recordFailure(subjectId, credentialLockOptions);
+        yield* store.recordFailure(subjectId, credentialLockOptions);
+        yield* store.recordFailure(subjectId, credentialLockOptions);
+        const locked = yield* store.findByEmail(email);
+
+        yield* check(
+          Option.isSome(locked) && Option.isSome(locked.value.lockedUntil),
+          "reaching the limit must lock the credential",
+        );
+        yield* TestClock.adjust(credentialLockOptions.lockDuration);
+        yield* store.recordFailure(subjectId, credentialLockOptions);
+        const afterExpiry = yield* store.findByEmail(email);
+
+        yield* check(
+          Option.isSome(afterExpiry) &&
+            afterExpiry.value.failedAttempts === 1 &&
+            Option.isNone(afterExpiry.value.lockedUntil),
+          "a failure after the lock expires must reset the count to one and not immediately re-lock",
+        );
+      }),
+    ),
+
+    credentialCase(
+      "unknown subjects are no-ops",
+      Effect.gen(function* () {
+        const store = yield* PasswordCredentialStore;
+        const email = emailOf("credential-unknown");
+        const subjectId = credentialConformanceSubject(email);
+
+        yield* store.recordFailure(subjectId, credentialLockOptions);
+        yield* store.recordSuccess(subjectId);
+        const credential = yield* store.findByEmail(email);
+
+        yield* check(
+          Option.isNone(credential),
+          "failure and success accounting must ignore subjects without a credential",
+        );
+      }),
+    ),
+  ];

package/src/testing/conformance/support.ts

@@ -0,0 +1,38 @@
+import { Effect, Schema } from "effect";
+
+import { Email, OtpDigest, SubjectId, TokenDigest } from "../../Schema";
+
+// Shared fabrication and assertion helpers for the store conformance suites.
+// Digests and identifiers are opaque strings to every store, so the suites
+// fabricate them directly and never need a codec.
+
+const decodeEmail = Schema.decodeSync(Email);
+const decodeTokenDigest = Schema.decodeSync(TokenDigest);
+const decodeOtpDigest = Schema.decodeSync(OtpDigest);
+
+export const decodeSubjectId = Schema.decodeSync(SubjectId);
+
+export const emailOf = (name: string) => decodeEmail(`${name}@conformance.test`);
+export const tokenDigestOf = (token: string) => decodeTokenDigest(`token-digest:${token}`);
+export const otpDigestOf = (otp: string) => decodeOtpDigest(`otp-digest:${otp}`);
+
+export const uuidOf = (index: number) =>
+  `00000000-0000-4000-8000-${String(index).padStart(12, "0")}`;
+
+export const check = (condition: boolean, message: string): Effect.Effect<void> =>
+  condition ? Effect.void : Effect.die(new Error(`Store conformance violation: ${message}`));
+
+export const expectFailure = <A, E extends { readonly _tag: string }, R>(
+  effect: Effect.Effect<A, E, R>,
+  tag: E["_tag"],
+  message: string,
+): Effect.Effect<void, never, R> =>
+  Effect.exit(effect).pipe(
+    Effect.flatMap((exit) =>
+      check(
+        exit._tag === "Failure" &&
+          exit.cause.reasons.some((reason) => reason._tag === "Fail" && reason.error._tag === tag),
+        message,
+      ),
+    ),
+  );

package/src/testing/crypto.ts

@@ -0,0 +1,55 @@
+import { Crypto, Effect, Layer } from "effect";
+
+/**
+ * Seeded, reproducible `Crypto.Crypto` for tests. The digest is deterministic
+ * and collision-poor but NOT cryptographic; never use this layer outside
+ * tests.
+ */
+export const layerCryptoDeterministic = (seed = 1): Layer.Layer<Crypto.Crypto> =>
+  Layer.sync(Crypto.Crypto)(() => {
+    let state = seed >>> 0;
+
+    // mulberry32
+    const next = () => {
+      state = (state + 0x6d2b79f5) | 0;
+      let t = Math.imul(state ^ (state >>> 15), 1 | state);
+
+      t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+
+      return (t ^ (t >>> 14)) >>> 0;
+    };
+
+    return Crypto.make({
+      randomBytes: (size) => {
+        const bytes = new Uint8Array(size);
+
+        for (let index = 0; index < size; index++) {
+          bytes[index] = next() & 0xff;
+        }
+
+        return bytes;
+      },
+      digest: (algorithm, data) => Effect.sync(() => fnvDigest(algorithm, data)),
+    });
+  });
+
+const fnvDigest = (algorithm: string, data: Uint8Array): Uint8Array => {
+  const output = new Uint8Array(32);
+
+  for (let word = 0; word < 8; word++) {
+    let hash = (0x811c9dc5 ^ Math.imul(word + 1, 0x9e3779b1)) >>> 0;
+
+    for (let index = 0; index < algorithm.length; index++) {
+      hash = Math.imul(hash ^ algorithm.charCodeAt(index), 0x01000193) >>> 0;
+    }
+    for (let index = 0; index < data.length; index++) {
+      hash = Math.imul(hash ^ (data[index] ?? 0), 0x01000193) >>> 0;
+    }
+    output[word * 4] = hash & 0xff;
+    output[word * 4 + 1] = (hash >>> 8) & 0xff;
+    output[word * 4 + 2] = (hash >>> 16) & 0xff;
+    output[word * 4 + 3] = (hash >>> 24) & 0xff;
+  }
+
+  return output;
+};

package/src/testing/keyring.ts

@@ -0,0 +1,17 @@
+import { Layer, Redacted, Schema } from "effect";
+
+import { AuthKeyring } from "../AuthTokenCodec";
+import { KeyId } from "../Schema";
+
+export const testKeyId = Schema.decodeSync(KeyId)("test-key-1");
+
+/** Static single-key keyring for tests; the secret is intentionally well known. */
+export const layerKeyringTest = Layer.succeed(AuthKeyring)({
+  activeKeyId: testKeyId,
+  keys: [
+    {
+      keyId: testKeyId,
+      secret: Redacted.make("effect-auth-test-secret-0123456789abcdef0123456789abcdef"),
+    },
+  ],
+});

package/src/totp/TotpActionEvidence.ts

@@ -0,0 +1,18 @@
+import { Context, type Effect, type Redacted } from "effect";
+
+import type { AuthInvocation } from "../operations/context";
+import type { AuthenticationEvidence } from "../sessions/models";
+import type { TotpActionRequired, TotpUnavailable } from "./errors";
+import type { TotpActionChallenge } from "./models";
+
+/** Fresh independent action proof, bound to the exact command. No weaker default exists. */
+export class TotpActionEvidence extends Context.Service<
+  TotpActionEvidence,
+  {
+    readonly verify: (input: {
+      readonly invocation: AuthInvocation;
+      readonly challenge: TotpActionChallenge;
+      readonly proof?: Redacted.Redacted<string>;
+    }) => Effect.Effect<AuthenticationEvidence, TotpActionRequired | TotpUnavailable>;
+  }
+>()("effect-auth/TotpActionEvidence") {}

package/src/totp/TotpPersistence.ts

@@ -0,0 +1,26 @@
+import { Context, type Effect } from "effect";
+
+import type { CommitJournal, PreparedCommit } from "../hooks/commit";
+import type { SubjectId } from "../Schema";
+import type { TotpUnavailable } from "./errors";
+import type { TotpDecision, TotpMutation, TotpSnapshot } from "./models";
+
+export type PrepareTotpCommit<A> = (
+  value: TotpDecision,
+  journal: CommitJournal,
+) => PreparedCommit<A>;
+
+/** Owns subject policy/revision, factor state and digest consumption in one native commit. */
+export class TotpPersistence extends Context.Service<
+  TotpPersistence,
+  {
+    readonly snapshot: (input: {
+      readonly moduleId: string;
+      readonly subjectId: SubjectId;
+    }) => Effect.Effect<TotpSnapshot | undefined, TotpUnavailable>;
+    readonly mutate: <A>(
+      input: TotpMutation,
+      prepare: PrepareTotpCommit<A>,
+    ) => Effect.Effect<PreparedCommit<A>, TotpUnavailable>;
+  }
+>()("effect-auth/TotpPersistence") {}

package/src/totp/TotpSecretKeys.ts

@@ -0,0 +1,15 @@
+import { Context, type Effect, type Redacted } from "effect";
+
+import type { TotpUnavailable } from "./errors";
+
+/** Consumer-owned AES-256 keys. Retain old key IDs until stored envelopes are replaced. */
+export class TotpSecretKeys extends Context.Service<
+  TotpSecretKeys,
+  {
+    readonly current: Effect.Effect<
+      { readonly keyId: string; readonly key: Redacted.Redacted<Uint8Array> },
+      TotpUnavailable
+    >;
+    readonly get: (keyId: string) => Effect.Effect<Redacted.Redacted<Uint8Array>, TotpUnavailable>;
+  }
+>()("effect-auth/TotpSecretKeys") {}