@yielded/auth 0.1.0-beta.1

package/src/AuthSession.ts

@@ -0,0 +1,298 @@
+import {
+  Context,
+  Crypto,
+  DateTime,
+  Duration,
+  Effect,
+  Layer,
+  Option,
+  type Redacted,
+  Schema,
+} from "effect";
+
+import { AuthTokenCodec } from "./AuthTokenCodec";
+import type { IdentityResolutionError, InvalidSession } from "./Errors";
+import { AuthTokenError } from "./Errors";
+import { AuthPolicy, revalidateSessionClaims } from "./Policy";
+import {
+  type Email,
+  type SubjectId,
+  SessionClaims,
+  SessionSummary,
+  SessionToken,
+  SessionTokenId,
+} from "./Schema";
+
+export class IssuedSession extends Schema.Class<IssuedSession>("effect-auth/IssuedSession")({
+  token: SessionToken,
+  summary: SessionSummary,
+}) {}
+
+/** A verified session and an optional replacement issued by rolling renewal. */
+export interface VerifiedSession {
+  readonly claims: SessionClaims;
+  readonly renewal: Option.Option<IssuedSession>;
+}
+
+const decodeSessionTokenId = Schema.decodeEffect(SessionTokenId);
+
+export interface IssueSessionOptions {
+  /** App-defined claims, signed into the envelope but opaque to effect-auth. */
+  readonly ext?: unknown;
+}
+
+/** Flow data available when effect-auth issues a session through its HTTP API. */
+export interface SessionExtContext {
+  readonly subjectId: SubjectId;
+  readonly email: Email;
+}
+
+/** A verified session whose app-defined extension has been decoded by its schema. */
+export interface VerifiedSessionWithExt<A> extends VerifiedSession {
+  readonly ext: Option.Option<A>;
+}
+
+export interface AuthSessionWithExtService<A> {
+  readonly issue: (subjectId: SubjectId, ext: A) => Effect.Effect<IssuedSession, AuthTokenError>;
+  readonly verify: (
+    token: Redacted.Redacted<string>,
+  ) => Effect.Effect<VerifiedSessionWithExt<A>, InvalidSession | AuthTokenError>;
+  /** Verifies the token and renews it when the configured rolling interval is due. */
+  readonly verifyAndRenew: (
+    token: Redacted.Redacted<string>,
+  ) => Effect.Effect<
+    VerifiedSessionWithExt<A>,
+    InvalidSession | AuthTokenError | IdentityResolutionError
+  >;
+  /** Issues from flow data using the optional builder in the declaration. */
+  readonly issueFromContext: (
+    context: SessionExtContext,
+  ) => Effect.Effect<IssuedSession, AuthTokenError>;
+}
+
+export type SessionExtBuilder<A> = (context: SessionExtContext) => Effect.Effect<A>;
+
+type AuthSessionWithExtOptions<S extends Schema.Codec<unknown, unknown>> = {
+  /** App-defined claims schema. The decoded type becomes the service extension type. */
+  readonly ext: S;
+} & (SessionExtContext extends S["Encoded"]
+  ? {
+      /** Overrides automatic decoding from the HTTP session context. */
+      readonly build?: SessionExtBuilder<NoInfer<S["Type"]>>;
+    }
+  : {
+      /** Required when the schema cannot decode the HTTP session context directly. */
+      readonly build: SessionExtBuilder<NoInfer<S["Type"]>>;
+    });
+
+type AuthSessionWithExtDefinition<S extends Schema.Codec<unknown, unknown>> =
+  SessionExtContext extends S["Encoded"]
+    ? S | AuthSessionWithExtOptions<S>
+    : AuthSessionWithExtOptions<S>;
+
+/** Context service class produced by {@link AuthSession.WithExt}. */
+export interface AuthSessionWithExtClass<Self, Id extends string, A> extends Context.ServiceClass<
+  Self,
+  Id,
+  AuthSessionWithExtService<A>
+> {
+  readonly ext: Schema.Codec<A, unknown>;
+  readonly layer: Layer.Layer<Self, never, AuthSession>;
+}
+
+const makeAuthSessionWithExt =
+  <Self>() =>
+  <const Id extends string, S extends Schema.Codec<unknown, unknown>>(
+    id: Id,
+    definition: AuthSessionWithExtDefinition<S>,
+  ): AuthSessionWithExtClass<Self, Id, S["Type"]> => {
+    const definitionIsSchema = Schema.isSchema(definition);
+    const ext = definitionIsSchema ? (definition as S) : definition.ext;
+    const build = definitionIsSchema ? undefined : definition.build;
+    const Service = Context.Service<Self, AuthSessionWithExtService<S["Type"]>>()(id);
+    const extCodec: Schema.Codec<S["Type"], S["Encoded"]> = ext;
+    const encodeExt = Schema.encodeEffect(extCodec);
+    const decodeContext = Schema.decodeEffect(extCodec);
+    // oxlint-disable-next-line no-restricted-properties -- SessionClaims.ext is an intentionally unknown wire boundary.
+    const decodeExt = Schema.decodeUnknownEffect(ext);
+
+    const layer = Layer.effect(
+      Service,
+      Effect.map(AuthSession, (sessions) => {
+        const issue = Effect.fn(`${id}.issue`)(function* (subjectId: SubjectId, ext: S["Type"]) {
+          const encoded = yield* encodeExt(ext).pipe(
+            Effect.mapError((error) =>
+              AuthTokenError.make({
+                message: `Session extension encoding failed: ${error.message}`,
+              }),
+            ),
+          );
+
+          return yield* sessions.issue(subjectId, { ext: encoded });
+        });
+
+        return Service.of({
+          issue,
+          verify: Effect.fn(`${id}.verify`)(function* (token) {
+            const claims = yield* sessions.verify(token);
+            const ext = yield* Effect.option(decodeExt(claims.ext));
+
+            return { claims, ext, renewal: Option.none() };
+          }),
+          verifyAndRenew: Effect.fn(`${id}.verifyAndRenew`)(function* (token) {
+            const verified = yield* sessions.verifyAndRenew(token);
+            const ext = yield* Effect.option(decodeExt(verified.claims.ext));
+
+            return { ...verified, ext };
+          }),
+          issueFromContext: Effect.fn(`${id}.issueFromContext`)(function* (context) {
+            const ext =
+              build === undefined
+                ? // The options type admits this branch only when the context
+                  // structurally satisfies the schema's encoded input. TS does
+                  // not narrow indexed access types through that conditional.
+                  yield* decodeContext(context as S["Encoded"]).pipe(
+                    Effect.mapError((error) =>
+                      AuthTokenError.make({
+                        message: `Session extension construction failed: ${error.message}`,
+                      }),
+                    ),
+                  )
+                : yield* build(context);
+
+            return yield* issue(context.subjectId, ext);
+          }),
+        });
+      }),
+    );
+
+    return Object.assign(Service, {
+      ext,
+      layer,
+    });
+  };
+
+/**
+ * Stateless session issuance and verification. Each token has a fixed expiry;
+ * authenticated HTTP activity can replace it after the configured renewal
+ * interval. There is no per-session revocation. Sign-out removes the browser
+ * cookie, and bulk invalidation happens through key removal or by bumping the
+ * configured session generation.
+ */
+export class AuthSession extends Context.Service<
+  AuthSession,
+  {
+    readonly issue: (
+      subjectId: SubjectId,
+      options?: IssueSessionOptions,
+    ) => Effect.Effect<IssuedSession, AuthTokenError>;
+    readonly verify: (
+      token: Redacted.Redacted<string>,
+    ) => Effect.Effect<SessionClaims, InvalidSession | AuthTokenError>;
+    /** Verifies the token and issues a replacement when rolling renewal is due. */
+    readonly verifyAndRenew: (
+      token: Redacted.Redacted<string>,
+    ) => Effect.Effect<VerifiedSession, InvalidSession | AuthTokenError | IdentityResolutionError>;
+  }
+>()("effect-auth/AuthSession") {
+  /**
+   * Declares an app-typed session service from one extension schema. Passing
+   * the schema directly automatically constructs extensions from compatible
+   * HTTP session context; schemas with derived inputs provide a `build`
+   * override. The core service remains opaque: this wrapper encodes before
+   * issuance and decodes after verification, preserving `None` for legacy or
+   * undecodable extensions.
+   */
+  static readonly WithExt = makeAuthSessionWithExt;
+
+  static readonly layer: Layer.Layer<AuthSession, never, AuthTokenCodec | Crypto.Crypto> =
+    Layer.effect(AuthSession)(
+      Effect.gen(function* () {
+        const policy = yield* AuthPolicy;
+        const codec = yield* AuthTokenCodec;
+        const crypto = yield* Crypto.Crypto;
+
+        const issue = Effect.fn("AuthSession.issue")(function* (
+          subjectId: SubjectId,
+          options?: IssueSessionOptions,
+        ) {
+          const now = yield* DateTime.now;
+          const expiresAt = DateTime.addDuration(now, policy.sessionLifetime);
+
+          const uuid = yield* crypto.randomUUIDv4.pipe(
+            Effect.mapError(() =>
+              AuthTokenError.make({ message: "Secure randomness unavailable" }),
+            ),
+          );
+
+          const tokenId = yield* decodeSessionTokenId(uuid).pipe(Effect.orDie);
+
+          const claims = SessionClaims.make({
+            ver: 1,
+            gen: policy.sessionGeneration,
+            kid: codec.activeKeyId,
+            sub: subjectId,
+            ...(options?.ext === undefined ? {} : { ext: options.ext }),
+            iss: policy.issuer,
+            aud: policy.audience,
+            iat: now,
+            exp: expiresAt,
+            jti: tokenId,
+          });
+
+          const token = yield* codec.encodeSession(claims);
+
+          return IssuedSession.make({
+            token,
+            summary: SessionSummary.make({ subjectId, expiresAt }),
+          });
+        });
+
+        const verify = Effect.fn("AuthSession.verify")(function* (
+          token: Redacted.Redacted<string>,
+        ) {
+          const claims = yield* codec.decodeSession(token);
+
+          return yield* revalidateSessionClaims(claims, {
+            issuer: policy.issuer,
+            audience: policy.audience,
+            sessionGeneration: policy.sessionGeneration,
+            allowedSigningKeyIds: new Set(codec.keyIds),
+          });
+        });
+
+        const renewIfDue = Effect.fn("AuthSession.renewIfDue")(function* (claims: SessionClaims) {
+          const now = yield* DateTime.now;
+          const issuedAtMillis = DateTime.toEpochMillis(claims.iat);
+          const tokenLifetimeMillis = DateTime.toEpochMillis(claims.exp) - issuedAtMillis;
+          const tokenAgeMillis = DateTime.toEpochMillis(now) - issuedAtMillis;
+          const configuredLifetimeMillis = Duration.toMillis(policy.sessionLifetime);
+          const renewalIntervalMillis = Duration.toMillis(policy.sessionRenewalInterval);
+
+          const renewalDue =
+            tokenLifetimeMillis !== configuredLifetimeMillis ||
+            tokenAgeMillis >= renewalIntervalMillis;
+
+          if (!renewalDue) return Option.none<IssuedSession>();
+
+          const renewed = yield* issue(
+            claims.sub,
+            claims.ext === undefined ? undefined : { ext: claims.ext },
+          );
+
+          return Option.some(renewed);
+        });
+
+        return AuthSession.of({
+          issue,
+          verify,
+          verifyAndRenew: Effect.fn("AuthSession.verifyAndRenew")(function* (token) {
+            const claims = yield* verify(token);
+            const renewal = yield* renewIfDue(claims);
+
+            return { claims, renewal };
+          }),
+        });
+      }),
+    );
+}

package/src/AuthStore.ts

@@ -0,0 +1,367 @@
+import { Context, DateTime, Duration, Effect, Layer, Schema, Semaphore } from "effect";
+
+import { AuthRateLimited, AuthStoreError, InvalidRegistration } from "./Errors";
+import {
+  type ConsumeChallenge,
+  type ConsumeRegistration,
+  type TokenDigest,
+  NewChallenge,
+  NewRegistration,
+  PendingRegistration,
+  timingSafeStringEqual,
+  VerifiedEmail,
+} from "./Schema";
+
+export type IssueChallengeError = AuthRateLimited | AuthStoreError;
+
+export const EmailOtpRejectionReason = Schema.Literals([
+  "missing_challenge",
+  "consumed_challenge",
+  "superseded_challenge",
+  "expired_challenge",
+  "missing_challenge_series",
+  "attempts_exhausted",
+  "bad_code",
+]);
+
+/** Internal rejection detail that the HTTP workflow collapses to `InvalidEmailOtp`. */
+export class EmailOtpRejected extends Schema.TaggedError<EmailOtpRejected>()("EmailOtpRejected", {
+  reason: EmailOtpRejectionReason,
+}) {}
+
+/**
+ * Deliberately narrow storage driver behind the store state machine: the
+ * in-memory map, Durable Object storage, or any keyed store whose writes
+ * become visible in order. Values handed to `put` are already JSON-safe
+ * encoded rows, so `get` legitimately yields `unknown`.
+ * Retain challenge rows through their original expiry, including after consumption.
+ */
+export class AuthStoreBackend extends Context.Service<
+  AuthStoreBackend,
+  {
+    /** Resolves the stored value for a key, or `undefined` when absent. */
+    readonly get: (key: string) => Effect.Effect<unknown, AuthStoreError>;
+    readonly put: (key: string, value: unknown) => Effect.Effect<void, AuthStoreError>;
+    readonly remove: (key: string) => Effect.Effect<void, AuthStoreError>;
+  }
+>()("effect-auth/AuthStoreBackend") {
+  /** In-memory backend for tests and local development; never durable. */
+  static readonly layerMemory: Layer.Layer<AuthStoreBackend> = Layer.sync(AuthStoreBackend)(() => {
+    const entries = new Map<string, unknown>();
+
+    return AuthStoreBackend.of({
+      get: (key) => Effect.sync(() => entries.get(key)),
+      put: (key, value) =>
+        Effect.sync(() => {
+          entries.set(key, value);
+        }),
+      remove: (key) =>
+        Effect.sync(() => {
+          entries.delete(key);
+        }),
+    });
+  });
+}
+
+// --- Stored rows ---------------------------------------------------------------
+
+class StoredChallenge extends Schema.Class<StoredChallenge>("effect-auth/StoredChallenge")({
+  challenge: NewChallenge,
+  consumed: Schema.Boolean,
+  superseded: Schema.Boolean,
+}) {}
+
+class StoredEmailSeries extends Schema.Class<StoredEmailSeries>("effect-auth/StoredEmailSeries")({
+  activeChallengeKey: Schema.UndefinedOr(Schema.String),
+  lastIssuedAt: Schema.DateTimeUtcFromMillis,
+  rollingAttempts: Schema.Natural,
+  windowExpiresAt: Schema.DateTimeUtcFromMillis,
+}) {}
+
+class StoredRegistration extends Schema.Class<StoredRegistration>("effect-auth/StoredRegistration")(
+  {
+    registration: NewRegistration,
+    consumed: Schema.Boolean,
+  },
+) {}
+
+// oxlint-disable-next-line no-restricted-properties -- AuthStoreBackend intentionally returns unknown persisted values.
+const decodeChallengeRow = Schema.decodeUnknownEffect(StoredChallenge);
+const encodeChallengeRow = Schema.encodeEffect(StoredChallenge);
+// oxlint-disable-next-line no-restricted-properties -- AuthStoreBackend intentionally returns unknown persisted values.
+const decodeSeriesRow = Schema.decodeUnknownEffect(StoredEmailSeries);
+const encodeSeriesRow = Schema.encodeEffect(StoredEmailSeries);
+// oxlint-disable-next-line no-restricted-properties -- AuthStoreBackend intentionally returns unknown persisted values.
+const decodeRegistrationRow = Schema.decodeUnknownEffect(StoredRegistration);
+const encodeRegistrationRow = Schema.encodeEffect(StoredRegistration);
+
+const challengeKey = (tokenDigest: string) => `challenge:${tokenDigest}`;
+const seriesKey = (purpose: string, email: string) => `series:${purpose}|${email}`;
+const registrationKey = (tokenDigest: string) => `registration:${tokenDigest}`;
+
+/**
+ * The canonical store state machine over an `AuthStoreBackend`. Operations are
+ * serialized through an internal semaphore, so the exactly-once consume
+ * guarantees hold even when the backend's reads and writes suspend. Runtimes
+ * that already serialize requests (a Durable Object's input gates) get a
+ * second, redundant layer of protection.
+ */
+const makeBackendAuthStore = Effect.gen(function* () {
+  const backend = yield* AuthStoreBackend;
+  const semaphore = yield* Semaphore.make(1);
+  const serialized = semaphore.withPermits(1);
+
+  const read = <Row, DecodeError>(
+    key: string,
+    decode: (value: unknown) => Effect.Effect<Row, DecodeError>,
+  ): Effect.Effect<Row | undefined, AuthStoreError> =>
+    backend.get(key).pipe(
+      Effect.mapError(() => AuthStoreError.make({ message: "Auth store read failed" })),
+      Effect.flatMap((value) =>
+        value === undefined
+          ? // The absent row is a meaningful result, not a discarded void.
+            // @effect-diagnostics-next-line effectSucceedWithVoid:off
+            Effect.succeed(undefined)
+          : decode(value).pipe(
+              Effect.mapError(() => AuthStoreError.make({ message: "Corrupt auth store row" })),
+            ),
+      ),
+    );
+
+  const write = <Row, EncodeError>(
+    key: string,
+    encode: (row: Row) => Effect.Effect<unknown, EncodeError>,
+    row: Row,
+  ): Effect.Effect<void, AuthStoreError> =>
+    encode(row).pipe(
+      Effect.mapError(() => AuthStoreError.make({ message: "Auth store write failed" })),
+      Effect.flatMap((value) =>
+        backend
+          .put(key, value)
+          .pipe(Effect.mapError(() => AuthStoreError.make({ message: "Auth store write failed" }))),
+      ),
+    );
+
+  const issueChallenge = Effect.fn("AuthStore.issueChallenge")(function* (input: NewChallenge) {
+    const now = DateTime.toEpochMillis(yield* DateTime.now);
+    const existing = yield* read(challengeKey(input.tokenDigest), decodeChallengeRow);
+
+    // An issuance is immutable; a retry must not reset its terminal state.
+    if (existing !== undefined) {
+      return yield* AuthRateLimited.make({ retryAfterSeconds: 1 });
+    }
+
+    const key = seriesKey(input.purpose, input.email);
+    const series = yield* read(key, decodeSeriesRow);
+    const cooldownMillis = Duration.toMillis(input.resendCooldown);
+
+    if (series !== undefined) {
+      const lastIssuedAt = DateTime.toEpochMillis(series.lastIssuedAt);
+
+      if (now < lastIssuedAt + cooldownMillis) {
+        return yield* AuthRateLimited.make({
+          retryAfterSeconds: Math.ceil((lastIssuedAt + cooldownMillis - now) / 1000),
+        });
+      }
+      if (series.activeChallengeKey !== undefined) {
+        const active = yield* read(series.activeChallengeKey, decodeChallengeRow);
+
+        if (active !== undefined && !active.superseded) {
+          yield* write(
+            series.activeChallengeKey,
+            encodeChallengeRow,
+            StoredChallenge.make({ ...active, superseded: true }),
+          );
+        }
+      }
+    }
+
+    // The rolling wrong-code budget survives resends and only resets once
+    // the previous window has fully expired.
+    const rollingAttempts =
+      series !== undefined && now < DateTime.toEpochMillis(series.windowExpiresAt)
+        ? series.rollingAttempts
+        : 0;
+
+    yield* write(
+      challengeKey(input.tokenDigest),
+      encodeChallengeRow,
+      StoredChallenge.make({ challenge: input, consumed: false, superseded: false }),
+    );
+    yield* write(
+      key,
+      encodeSeriesRow,
+      StoredEmailSeries.make({
+        activeChallengeKey: challengeKey(input.tokenDigest),
+        lastIssuedAt: yield* DateTime.now,
+        rollingAttempts,
+        windowExpiresAt: input.expiresAt,
+      }),
+    );
+  });
+
+  const consumeChallenge = Effect.fn("AuthStore.consumeChallenge")(function* (
+    input: ConsumeChallenge,
+  ) {
+    const reject = (reason: typeof EmailOtpRejectionReason.Type) =>
+      EmailOtpRejected.make({ reason });
+
+    const now = DateTime.toEpochMillis(yield* DateTime.now);
+    const row = yield* read(challengeKey(input.tokenDigest), decodeChallengeRow);
+
+    if (row === undefined) {
+      return yield* reject("missing_challenge");
+    }
+    const key = seriesKey(row.challenge.purpose, row.challenge.email);
+    const series = yield* read(key, decodeSeriesRow);
+
+    if (row.consumed) return yield* reject("consumed_challenge");
+    if (row.superseded) return yield* reject("superseded_challenge");
+    if (now >= DateTime.toEpochMillis(row.challenge.expiresAt)) {
+      return yield* reject("expired_challenge");
+    }
+    if (series === undefined) return yield* reject("missing_challenge_series");
+    if (series.rollingAttempts >= row.challenge.attemptLimit) {
+      return yield* reject("attempts_exhausted");
+    }
+    const candidate = input.otpDigests[row.challenge.otpKeyId];
+
+    const matches =
+      candidate !== undefined && timingSafeStringEqual(candidate, row.challenge.otpDigest);
+
+    if (!matches) {
+      yield* write(
+        key,
+        encodeSeriesRow,
+        StoredEmailSeries.make({ ...series, rollingAttempts: series.rollingAttempts + 1 }),
+      );
+
+      return yield* reject("bad_code");
+    }
+    yield* write(
+      challengeKey(input.tokenDigest),
+      encodeChallengeRow,
+      StoredChallenge.make({ ...row, consumed: true }),
+    );
+    yield* backend
+      .remove(key)
+      .pipe(Effect.mapError(() => AuthStoreError.make({ message: "Auth store write failed" })));
+
+    return VerifiedEmail.make({
+      email: row.challenge.email,
+      purpose: row.challenge.purpose,
+    });
+  });
+
+  const issueRegistration = Effect.fn("AuthStore.issueRegistration")(function* (
+    input: NewRegistration,
+  ) {
+    yield* write(
+      registrationKey(input.tokenDigest),
+      encodeRegistrationRow,
+      StoredRegistration.make({ registration: input, consumed: false }),
+    );
+  });
+
+  const inspectRegistration = Effect.fn("AuthStore.inspectRegistration")(function* (
+    tokenDigest: TokenDigest,
+  ) {
+    const now = DateTime.toEpochMillis(yield* DateTime.now);
+    const row = yield* read(registrationKey(tokenDigest), decodeRegistrationRow);
+
+    if (
+      row === undefined ||
+      row.consumed ||
+      now >= DateTime.toEpochMillis(row.registration.expiresAt)
+    ) {
+      return yield* InvalidRegistration.make();
+    }
+
+    return PendingRegistration.make({
+      registrationId: row.registration.registrationId,
+      email: row.registration.email,
+      purpose: row.registration.purpose,
+      issuedAt: row.registration.issuedAt,
+      expiresAt: row.registration.expiresAt,
+    });
+  });
+
+  const consumeRegistration = Effect.fn("AuthStore.consumeRegistration")(function* (
+    input: ConsumeRegistration,
+  ) {
+    const now = DateTime.toEpochMillis(yield* DateTime.now);
+    const row = yield* read(registrationKey(input.tokenDigest), decodeRegistrationRow);
+
+    if (
+      row === undefined ||
+      row.consumed ||
+      now >= DateTime.toEpochMillis(row.registration.expiresAt)
+    ) {
+      return yield* InvalidRegistration.make();
+    }
+    yield* write(
+      registrationKey(input.tokenDigest),
+      encodeRegistrationRow,
+      StoredRegistration.make({ ...row, consumed: true }),
+    );
+  });
+
+  return {
+    issueChallenge: (input: NewChallenge) => serialized(issueChallenge(input)),
+    consumeChallenge: (input: ConsumeChallenge) => serialized(consumeChallenge(input)),
+    issueRegistration: (input: NewRegistration) => serialized(issueRegistration(input)),
+    inspectRegistration: (tokenDigest: TokenDigest) => serialized(inspectRegistration(tokenDigest)),
+    consumeRegistration: (input: ConsumeRegistration) => serialized(consumeRegistration(input)),
+  };
+});
+
+/**
+ * Semantic persistence port for challenges and pending registrations, not
+ * CRUD. The consume operations must be atomic: exactly one of concurrent
+ * valid consumptions may succeed. Per-challenge attempts, resend cooldown,
+ * and email-scoped issuance limits live behind this contract; IP/network
+ * limits stay at the edge.
+ *
+ * Adapters either implement this interface directly against a store with real
+ * transactions, or provide an `AuthStoreBackend` to `layerBackend`. Either
+ * way, the conformance suite exported from `effect-auth/Testing` is the
+ * acceptance test.
+ */
+export class AuthStore extends Context.Service<
+  AuthStore,
+  {
+    readonly issueChallenge: (input: NewChallenge) => Effect.Effect<void, IssueChallengeError>;
+    /**
+     * Checks token digest, OTP digest, purpose, expiry, supersession,
+     * consumption, and attempt budget as one atomic operation. A failed
+     * comparison increments the rolling attempt budget; success consumes the
+     * challenge. The workflow logs the internal rejection reason, then
+     * collapses every failure to the public `InvalidEmailOtp`.
+     */
+    readonly consumeChallenge: (
+      input: ConsumeChallenge,
+    ) => Effect.Effect<VerifiedEmail, EmailOtpRejected | AuthStoreError>;
+    readonly issueRegistration: (input: NewRegistration) => Effect.Effect<void, AuthStoreError>;
+    readonly inspectRegistration: (
+      tokenDigest: TokenDigest,
+    ) => Effect.Effect<PendingRegistration, InvalidRegistration | AuthStoreError>;
+    readonly consumeRegistration: (
+      input: ConsumeRegistration,
+    ) => Effect.Effect<void, InvalidRegistration | AuthStoreError>;
+  }
+>()("effect-auth/AuthStore") {
+  /** The canonical state machine over whichever `AuthStoreBackend` is provided. */
+  static readonly layerBackend: Layer.Layer<AuthStore, never, AuthStoreBackend> =
+    Layer.effect(AuthStore)(makeBackendAuthStore);
+
+  /**
+   * In-memory adapter for tests and local development. Never a durable
+   * production adapter.
+   */
+  static readonly layerMemory: Layer.Layer<AuthStore> = AuthStore.layerBackend.pipe(
+    Layer.provide(AuthStoreBackend.layerMemory),
+  );
+}
+
+export { AuthStoreDecisions, type ChallengeConsumeDecision } from "./internal/AuthStoreDecisions";
+export type { ConsumeDecision } from "./auth/ConsumeDecision";