@yielded/auth 0.1.0-beta.1

package/src/oauth/OAuthConnectionStore.ts

@@ -0,0 +1,59 @@
+import { Context, Effect, Layer, Option } from "effect";
+
+import type { AuthStoreError } from "../Errors";
+import type { SubjectId } from "../Schema";
+import type { OAuthConnection, OAuthProviderKey } from "./schema";
+
+/**
+ * Consumer-implemented persistence for provider connections, keyed by
+ * `(provider, subjectId)`. This is the package's explicit token-persistence
+ * boundary:
+ *
+ * - **Production adapters MUST encrypt the token values at rest.** The
+ *   `OAuthConnection` token fields are `Redacted`; an adapter unwraps them
+ *   with `Redacted.value` only inside its encryption boundary and re-wraps on
+ *   read. Storing the unwrapped values verbatim is a security defect.
+ * - Token values must never appear in logs, errors, or telemetry; the
+ *   `Redacted` wrapper protects accidental stringification, nothing more.
+ * - `put` replaces any existing connection for the same key.
+ */
+export class OAuthConnectionStore extends Context.Service<
+  OAuthConnectionStore,
+  {
+    readonly get: (
+      provider: OAuthProviderKey,
+      subjectId: SubjectId,
+    ) => Effect.Effect<Option.Option<OAuthConnection>, AuthStoreError>;
+    readonly put: (connection: OAuthConnection) => Effect.Effect<void, AuthStoreError>;
+    readonly remove: (
+      provider: OAuthProviderKey,
+      subjectId: SubjectId,
+    ) => Effect.Effect<void, AuthStoreError>;
+  }
+>()("effect-auth/OAuthConnectionStore") {
+  /**
+   * In-memory adapter for tests and local development; never durable and
+   * never encrypted, so never a production adapter.
+   */
+  static readonly layerMemory: Layer.Layer<OAuthConnectionStore> = Layer.sync(OAuthConnectionStore)(
+    () => {
+      const connections = new Map<string, OAuthConnection>();
+      const key = (provider: OAuthProviderKey, subjectId: SubjectId) => `${provider}|${subjectId}`;
+
+      return OAuthConnectionStore.of({
+        get: (provider, subjectId) =>
+          Effect.sync(() => Option.fromNullishOr(connections.get(key(provider, subjectId)))),
+
+        put: (connection) =>
+          Effect.sync(() => {
+            connections.set(key(connection.provider, connection.subjectId), connection);
+          }),
+
+        remove: (provider, subjectId) =>
+          Effect.sync(() => {
+            connections.delete(key(provider, subjectId));
+          }),
+      });
+    },
+  );
+}

package/src/oauth/OAuthLinkTransactionProtector.ts

@@ -0,0 +1,58 @@
+import { Context, type Effect, Layer, Schema } from "effect";
+
+import { OAuthLinkTransactionContext } from "./accountsModels";
+import { OAuthUnavailable } from "./signInErrors";
+import type { OAuthTransactionSecrets } from "./signInModels";
+import { OAuthEncryptionKeyId, OAuthSealedTransaction } from "./signInModels";
+import { snapshotOAuthSync } from "./signInSnapshot";
+import { transactionEncryption, type OAuthTransactionKeyring } from "./transactionEncryption";
+
+const codec = Schema.fromJsonString(
+  Schema.Tuple([
+    Schema.Literal("effect-auth/oauth-link-aead/v1"),
+    OAuthSealedTransaction.fields.format,
+    OAuthEncryptionKeyId,
+    OAuthLinkTransactionContext,
+  ]),
+);
+
+const encoder = new TextEncoder();
+
+const aad = (context: OAuthLinkTransactionContext, keyId: string) => {
+  const value = Schema.encodeSync(codec)([
+    "effect-auth/oauth-link-aead/v1",
+    "oauth-xchacha20poly1305-v1",
+    keyId,
+    snapshotOAuthSync(OAuthLinkTransactionContext, context),
+  ]);
+
+  if (value.length > 16384) throw OAuthUnavailable.make({});
+  const bytes = encoder.encode(value);
+
+  if (bytes.length > 16384) {
+    bytes.fill(0);
+    throw OAuthUnavailable.make({});
+  }
+
+  return bytes;
+};
+
+/** Typed authenticated-link domain, isolated from guest sign-in. Dedicated keyring
+ * retention covers issued and claimed link horizons and deployment convergence;
+ * link-binder signing keys have their own independent retention obligation. */
+export class OAuthLinkTransactionProtector extends Context.Service<
+  OAuthLinkTransactionProtector,
+  {
+    readonly seal: (input: {
+      readonly context: OAuthLinkTransactionContext;
+      readonly secrets: OAuthTransactionSecrets;
+    }) => Effect.Effect<OAuthSealedTransaction, OAuthUnavailable>;
+    readonly open: (input: {
+      readonly context: OAuthLinkTransactionContext;
+      readonly sealed: OAuthSealedTransaction;
+    }) => Effect.Effect<OAuthTransactionSecrets, OAuthUnavailable>;
+  }
+>()("effect-auth/OAuthLinkTransactionProtector") {
+  static readonly xchacha20poly1305 = (keyring: OAuthTransactionKeyring) =>
+    Layer.effect(this, transactionEncryption(OAuthLinkTransactionContext, aad, keyring));
+}

package/src/oauth/OAuthProtocol.ts

@@ -0,0 +1,39 @@
+import { Context, type DateTime, type Effect } from "effect";
+
+import type { RequestBindingFlowId } from "../operations/requestBinding";
+import type { OAuthProviderKey } from "./schema";
+import type { OAuthProtocolRejected, OAuthRejected, OAuthUnavailable } from "./signInErrors";
+import type {
+  OAuthCallbackId,
+  OAuthCodeResponse,
+  OAuthProtocolConfiguration,
+  OAuthProtocolPreparation,
+  OAuthTransactionSecrets,
+  OAuthVerifiedExternalIdentity,
+} from "./signInModels";
+
+/** Configured protocol authority. Resolve exact captured configuration generations;
+ * preparation/exchange run outside persistence owners. Discard all provider tokens
+ * in sign-in adapters; profile/email never selects application identity.
+ * The adapter owns canonical issuer, exact configured redirect, fixed provider
+ * authorization origin/parameters, S256 and nonce validation, and retention of
+ * each configuration generation through its issued flow horizon. Never discover
+ * a caller-supplied issuer or substitute a newer configuration at completion.
+ * No network implementation is installed by the core method.
+ */
+export class OAuthProtocol extends Context.Service<
+  OAuthProtocol,
+  {
+    readonly prepareAuthorization: (input: {
+      readonly provider: OAuthProviderKey;
+      readonly callbackId: typeof OAuthCallbackId.Type;
+      readonly flowId: RequestBindingFlowId;
+    }) => Effect.Effect<OAuthProtocolPreparation, OAuthRejected | OAuthUnavailable>;
+    readonly exchangeVerifiedIdentity: (input: {
+      readonly configuration: OAuthProtocolConfiguration;
+      readonly response: OAuthCodeResponse;
+      readonly secrets: OAuthTransactionSecrets;
+      readonly verificationStartedAt: DateTime.Utc;
+    }) => Effect.Effect<OAuthVerifiedExternalIdentity, OAuthProtocolRejected | OAuthUnavailable>;
+  }
+>()("effect-auth/OAuthProtocol") {}

package/src/oauth/OAuthProvider.ts

@@ -0,0 +1,126 @@
+import { Duration, Effect, Option, Redacted, Schema } from "effect";
+import type { HttpClientRequest } from "effect/unstable/http";
+
+import { OAuthGrantRejected, OAuthProviderError } from "./errors";
+import type { OAuthIdentity, OAuthProviderKey } from "./schema";
+
+/**
+ * One token-endpoint grant in wire-relative form: lifetimes are durations
+ * because the response carries `expires_in`, not instants. The OAuth workflow
+ * stamps absolute expirations against its own clock.
+ */
+export interface OAuthTokenGrant {
+  readonly accessToken: Redacted.Redacted<string>;
+  readonly tokenType: string;
+  readonly expiresIn: Option.Option<Duration.Duration>;
+  readonly refreshToken: Option.Option<Redacted.Redacted<string>>;
+  readonly refreshTokenExpiresIn: Option.Option<Duration.Duration>;
+  readonly scope: Option.Option<string>;
+}
+
+/** Where and how the workflow fetches the provider's account identity. */
+export interface OAuthIdentityEndpoint {
+  readonly url: string;
+  /** Static headers merged into the request; authorization is added by the workflow. */
+  readonly headers: Readonly<Record<string, string>>;
+  /** Validates the untrusted identity payload and normalizes it. */
+  readonly decode: (payload: unknown) => Effect.Effect<OAuthIdentity, OAuthProviderError>;
+}
+
+/**
+ * Everything provider-specific about one OAuth integration: endpoints,
+ * credentials, response mappings, and identity normalization. Deliberately
+ * data-plus-decoders — the `OAuth` workflow owns every orchestration step
+ * (state, redirects, code exchange, refresh, revocation execution), so a
+ * provider cannot diverge from the flow's security behavior.
+ */
+export interface OAuthProvider {
+  readonly key: OAuthProviderKey;
+  readonly displayName: string;
+  readonly clientId: string;
+  readonly clientSecret: Redacted.Redacted<string>;
+  readonly endpoints: {
+    readonly authorization: string;
+    readonly token: string;
+  };
+  /** Scopes requested at authorization; when empty the `scope` parameter is omitted. */
+  readonly scopes: ReadonlyArray<string>;
+  /** Extra static query parameters for the authorization redirect. */
+  readonly authorizationParams: Readonly<Record<string, string>>;
+  /**
+   * Decodes one token-endpoint JSON payload into a normalized grant, or into
+   * `OAuthGrantRejected` when the payload is a well-formed OAuth error.
+   * Providers following RFC 6749 use {@link decodeStandardTokenGrant}.
+   */
+  readonly decodeTokenGrant: (
+    payload: unknown,
+  ) => Effect.Effect<OAuthTokenGrant, OAuthGrantRejected | OAuthProviderError>;
+  readonly identity: OAuthIdentityEndpoint;
+  /**
+   * Builds the provider's token-revocation request; `None` when the provider
+   * offers no revocation API. The workflow executes the request and treats
+   * 2xx and "grant already gone" statuses (404, 422) as revoked.
+   */
+  readonly revocation: Option.Option<
+    (accessToken: Redacted.Redacted<string>) => HttpClientRequest.HttpClientRequest
+  >;
+}
+
+// --- Standard token responses -----------------------------------------------------
+
+const StandardTokenSuccess = Schema.Struct({
+  access_token: Schema.NonEmptyString,
+  token_type: Schema.optionalKey(Schema.String),
+  expires_in: Schema.optionalKey(Schema.Finite),
+  refresh_token: Schema.optionalKey(Schema.NonEmptyString),
+  refresh_token_expires_in: Schema.optionalKey(Schema.Finite),
+  scope: Schema.optionalKey(Schema.String),
+});
+
+const StandardTokenError = Schema.Struct({
+  error: Schema.NonEmptyString,
+});
+
+const StandardTokenResponse = Schema.Union([StandardTokenSuccess, StandardTokenError]);
+
+// oxlint-disable-next-line no-restricted-properties -- Token endpoint payloads are untrusted JSON.
+const decodeStandardTokenResponse = Schema.decodeUnknownEffect(StandardTokenResponse);
+
+const positiveSeconds = (seconds: number | undefined): Option.Option<Duration.Duration> =>
+  seconds !== undefined && seconds > 0 ? Option.some(Duration.seconds(seconds)) : Option.none();
+
+/**
+ * Token-grant decoder for RFC 6749 token responses (`access_token`,
+ * `expires_in`, `refresh_token`, …) that also recognizes the standard
+ * `{ "error": … }` payload — which some providers, GitHub included, return
+ * with status 200.
+ */
+export const decodeStandardTokenGrant =
+  (provider: OAuthProviderKey) =>
+  (payload: unknown): Effect.Effect<OAuthTokenGrant, OAuthGrantRejected | OAuthProviderError> =>
+    decodeStandardTokenResponse(payload).pipe(
+      Effect.mapError(() =>
+        OAuthProviderError.make({
+          provider,
+          message: "The token endpoint returned an unrecognized response",
+        }),
+      ),
+      Effect.flatMap((response) =>
+        "error" in response
+          ? OAuthGrantRejected.make({ provider, code: response.error })
+          : Effect.succeed<OAuthTokenGrant>({
+              accessToken: Redacted.make(response.access_token),
+              tokenType: (response.token_type ?? "bearer").toLowerCase(),
+              expiresIn: positiveSeconds(response.expires_in),
+              refreshToken:
+                response.refresh_token !== undefined
+                  ? Option.some(Redacted.make(response.refresh_token))
+                  : Option.none(),
+              refreshTokenExpiresIn: positiveSeconds(response.refresh_token_expires_in),
+              scope:
+                response.scope !== undefined && response.scope !== ""
+                  ? Option.some(response.scope)
+                  : Option.none(),
+            }),
+      ),
+    );

package/src/oauth/OAuthProviders.ts

@@ -0,0 +1,53 @@
+import { Context, Effect, Layer } from "effect";
+
+import { UnknownOAuthProvider } from "./errors";
+import type { OAuthProvider } from "./OAuthProvider";
+import type { OAuthProviderKey } from "./schema";
+
+/**
+ * The set of configured OAuth providers. Applications construct the complete
+ * set in one place, so provider selection is deterministic and duplicate keys
+ * fail during layer construction:
+ *
+ * ```ts
+ * const OAuthLive = OAuth.layer.pipe(
+ *   Layer.provide(OAuthProviders.layer([
+ *     makeGithubOAuthProvider({ clientId, clientSecret }),
+ *   ])),
+ * )
+ * ```
+ */
+export class OAuthProviders extends Context.Service<
+  OAuthProviders,
+  {
+    readonly lookup: (key: OAuthProviderKey) => Effect.Effect<OAuthProvider, UnknownOAuthProvider>;
+  }
+>()("effect-auth/OAuthProviders") {
+  static readonly layer = (configured: Iterable<OAuthProvider> = []): Layer.Layer<OAuthProviders> =>
+    Layer.effect(
+      OAuthProviders,
+      Effect.gen(function* () {
+        const providers = new Map<OAuthProviderKey, OAuthProvider>();
+
+        for (const provider of configured) {
+          if (providers.has(provider.key)) {
+            return yield* Effect.die(
+              new Error(`OAuth provider "${provider.key}" is configured more than once`),
+            );
+          }
+          providers.set(provider.key, provider);
+        }
+
+        return OAuthProviders.of({
+          lookup: (key) =>
+            Effect.suspend(() => {
+              const provider = providers.get(key);
+
+              return provider === undefined
+                ? Effect.fail(UnknownOAuthProvider.make({ provider: key }))
+                : Effect.succeed(provider);
+            }),
+        });
+      }),
+    );
+}

package/src/oauth/OAuthRegistrationIntents.ts

@@ -0,0 +1,42 @@
+import { Context, Schema, type Effect } from "effect";
+
+import type { PreparedCommit } from "../hooks/commit";
+import type { PrepareOAuthCommit } from "./OAuthSignInPersistence";
+import { OAuthRegistrationIntent } from "./registrationModels";
+import type { OAuthUnavailable } from "./signInErrors";
+import {
+  OAuthSettlementDecision,
+  type OAuthClaim,
+  type OAuthVerifiedExternalIdentity,
+} from "./signInModels";
+
+export const OAuthRegistrationSettlement = Schema.Union([
+  OAuthSettlementDecision,
+  Schema.TaggedStruct("RegistrationIssued", { intent: OAuthRegistrationIntent }),
+]);
+
+export type OAuthRegistrationSettlement = typeof OAuthRegistrationSettlement.Type;
+
+/** Optional replacement for VERIFIED sign-in settlement, under the same flow and
+ * identity authority. Existing active credentials sign in. Only a globally unowned,
+ * currently permitted and unreserved full tuple may create the exact supplied restricted intent.
+ * Connected-only, disabled or otherwise owned identities never count as unknown.
+ * Exact claim/context/deadline CAS, terminal erasure, unique intent/reference,
+ * ownership check, and the prepared decision commit together. No provisioning.
+ * If intent is absent/expired, unknown identity commits Rejected. Retain original
+ * binder and immutable time horizons. Unknown outcomes discard every receipt.
+ */
+export class OAuthRegistrationIntents extends Context.Service<
+  OAuthRegistrationIntents,
+  {
+    readonly settle: <A>(
+      input: {
+        readonly claim: OAuthClaim;
+        readonly identity: OAuthVerifiedExternalIdentity;
+        readonly intent?: OAuthRegistrationIntent;
+        readonly nowMillis: number;
+      },
+      prepare: PrepareOAuthCommit<OAuthRegistrationSettlement, A>,
+    ) => Effect.Effect<PreparedCommit<A>, OAuthUnavailable>;
+  }
+>()("effect-auth/OAuthRegistrationIntents") {}

package/src/oauth/OAuthReturnTargets.ts

@@ -0,0 +1,44 @@
+import { Context, Effect, Layer, Schema } from "effect";
+
+import { OAuthConfigurationError, OAuthRejected, type OAuthUnavailable } from "./signInErrors";
+import { OAuthReturnTarget } from "./signInModels";
+
+/** Application authority; resolve before issuance and retain that exact route.
+ * The callback cannot select a replacement. Core never performs redirects. */
+export class OAuthReturnTargets extends Context.Service<
+  OAuthReturnTargets,
+  {
+    readonly resolve: (
+      input: string,
+    ) => Effect.Effect<typeof OAuthReturnTarget.Type, OAuthRejected | OAuthUnavailable>;
+  }
+>()("effect-auth/OAuthReturnTargets") {
+  static readonly exactRoutes = (routes: ReadonlyArray<string>) => {
+    const captured = [...routes];
+
+    return Layer.effect(
+      this,
+      Effect.gen(function* () {
+        const checked = yield* Schema.decodeEffect(
+          Schema.Array(OAuthReturnTarget).check(Schema.isMinLength(1), Schema.isMaxLength(128)),
+        )(captured).pipe(
+          Effect.mapError(() => OAuthConfigurationError.make({ reason: "return-target" })),
+        );
+
+        const allowed = new Set<string>(checked);
+
+        return OAuthReturnTargets.of({
+          resolve: Effect.fn("OAuthReturnTargets.resolve")(function* (input) {
+            const target = yield* Schema.decodeEffect(OAuthReturnTarget)(input).pipe(
+              Effect.mapError(() => OAuthRejected.make({})),
+            );
+
+            if (!allowed.has(target)) return yield* OAuthRejected.make({});
+
+            return target;
+          }),
+        });
+      }),
+    );
+  };
+}

package/src/oauth/OAuthSignInPersistence.ts

@@ -0,0 +1,91 @@
+import { Context, type Effect } from "effect";
+
+import type { CommitJournal, PreparedCommit } from "../hooks/commit";
+import type { RequestBindingFlowId } from "../operations/requestBinding";
+import type { TokenDigest } from "../Schema";
+import type { OAuthProviderKey } from "./schema";
+import type { OAuthUnavailable } from "./signInErrors";
+import type {
+  OAuthCallbackId,
+  OAuthClaim,
+  OAuthClaimDecision,
+  OAuthClaimId,
+  OAuthCleanupInput,
+  OAuthIssueDecision,
+  OAuthIssuer,
+  OAuthModuleId,
+  OAuthPendingFlow,
+  OAuthSettlementDecision,
+  OAuthVerifiedExternalIdentity,
+} from "./signInModels";
+
+export type PrepareOAuthCommit<Value, A> = (
+  value: Value,
+  journal: CommitJournal,
+) => PreparedCommit<A>;
+
+/** Semantic commands with one physical authority per call. Prepare is synchronous
+ * and runs before commit; unknown outcomes discard receipts. No callback replay.
+ * Standalone adapters reject ambient owners; bound services share an explicit owner.
+ * No method accepts a bearer, callback code, plaintext transaction secret, or Claims.
+ */
+export class OAuthSignInPersistence extends Context.Service<
+  OAuthSignInPersistence,
+  {
+    /** Duplicate module/flow or module/command rejects; never return an existing row. */
+    readonly issue: <A>(
+      input: OAuthPendingFlow,
+      prepare: PrepareOAuthCommit<OAuthIssueDecision, A>,
+    ) => Effect.Effect<PreparedCommit<A>, OAuthUnavailable>;
+    /** Atomically check Pending, module/generation/provider/callback/state/binder,
+     * authoritative expiry, and required/unsupported response issuer. Wrong binding
+     * does not mutate. Only one claim; no reset, lease renewal or re-exchange.
+     * Use authority time; set claimExpiresAt = claimedAt + captured claimLifetime.
+     */
+    readonly claim: <A>(
+      input: {
+        readonly moduleId: typeof OAuthModuleId.Type;
+        readonly generation: number;
+        readonly flowId: RequestBindingFlowId;
+        readonly provider: OAuthProviderKey;
+        readonly callbackId: typeof OAuthCallbackId.Type;
+        readonly stateDigest: TokenDigest;
+        readonly requestBindingVerifier: TokenDigest;
+        readonly requestBindingExpiresAtMillis: number;
+        readonly responseIssuer?: typeof OAuthIssuer.Type;
+        readonly claimId: typeof OAuthClaimId.Type;
+        readonly nowMillis: number;
+      },
+      prepare: PrepareOAuthCommit<OAuthClaimDecision, A>,
+    ) => Effect.Effect<PreparedCommit<A>, OAuthUnavailable>;
+    /** CAS exact claim/context/generation before the captured deadline. Erase sealed
+     * material on every terminal result. Verified resolves the full external tuple
+     * to an active subject, usable OAuth credential and matching shared factor in
+     * this same owner. No match commits Rejected, with no provisioning or session.
+     * A stale claim rejects; infrastructure/unknown outcome is unavailable.
+     */
+    readonly settle: <A>(
+      input: {
+        readonly claim: OAuthClaim;
+        readonly outcome:
+          | { readonly _tag: "Verified"; readonly identity: OAuthVerifiedExternalIdentity }
+          | { readonly _tag: "Cancelled" | "Rejected" | "Ambiguous" };
+        readonly nowMillis: number;
+      },
+      prepare: PrepareOAuthCommit<OAuthSettlementDecision, A>,
+    ) => Effect.Effect<PreparedCommit<A>, OAuthUnavailable>;
+    /** At most limit rows: expire Pending -> Rejected and Claimed -> Ambiguous,
+     * erasing sealed material; never make them Pending again. Remove terminal
+     * tombstones only after their original retentionUntil and claim deadline.
+     * Decode OAuthCleanupInput (integer limit 1..1000) before querying.
+     * Re-read authority time and exact status/version for each conditional write.
+     */
+    readonly cleanup: <A>(
+      input: OAuthCleanupInput,
+      prepare: PrepareOAuthCommit<
+        { readonly terminalized: number; readonly removed: number; readonly hasMore: boolean },
+        A
+      >,
+    ) => Effect.Effect<PreparedCommit<A>, OAuthUnavailable>;
+  }
+>()("effect-auth/OAuthSignInPersistence") {}

package/src/oauth/OAuthStateDecisions.ts

@@ -0,0 +1,16 @@
+import { Context, type Effect } from "effect";
+
+import type { ConsumeDecision } from "../auth/ConsumeDecision";
+import type { AuthStoreError } from "../Errors";
+import type { TokenDigest } from "../Schema";
+import type { OAuthState } from "./schema";
+
+/** Transaction-scoped consume; translate rejection only after the owner commits. */
+export class OAuthStateDecisions extends Context.Service<
+  OAuthStateDecisions,
+  {
+    readonly consumeOAuthState: (
+      digest: TokenDigest,
+    ) => Effect.Effect<ConsumeDecision<OAuthState>, AuthStoreError>;
+  }
+>()("effect-auth/OAuthStateDecisions") {}

package/src/oauth/OAuthStateStore.ts

@@ -0,0 +1,102 @@
+import { Context, DateTime, Effect, Layer, Schema, Semaphore } from "effect";
+
+import { AuthStoreBackend } from "../AuthStore";
+import { AuthStoreError } from "../Errors";
+import type { TokenDigest } from "../Schema";
+import { InvalidOAuthState } from "./errors";
+import { OAuthState } from "./schema";
+
+class StoredOAuthState extends Schema.Class<StoredOAuthState>("effect-auth/StoredOAuthState")({
+  state: OAuthState,
+  consumed: Schema.Boolean,
+}) {}
+
+// oxlint-disable-next-line no-restricted-properties -- AuthStoreBackend intentionally returns unknown persisted values.
+const decodeStateRow = Schema.decodeUnknownEffect(StoredOAuthState);
+const encodeStateRow = Schema.encodeEffect(StoredOAuthState);
+
+const stateKey = (stateDigest: string) => `oauth-state:${stateDigest}`;
+
+const readFailed = AuthStoreError.make({ message: "Auth store read failed" });
+const writeFailed = AuthStoreError.make({ message: "Auth store write failed" });
+
+const makeBackendOAuthStateStore = Effect.gen(function* () {
+  const backend = yield* AuthStoreBackend;
+  const semaphore = yield* Semaphore.make(1);
+  const serialized = semaphore.withPermits(1);
+
+  const issue = Effect.fn("OAuthStateStore.issue")(
+    function* (state: OAuthState) {
+      const row = yield* encodeStateRow(StoredOAuthState.make({ state, consumed: false }));
+
+      yield* backend.put(stateKey(state.stateDigest), row);
+    },
+    Effect.mapError(() => writeFailed),
+  );
+
+  const consume = Effect.fn("OAuthStateStore.consume")(function* (stateDigest: TokenDigest) {
+    const now = DateTime.toEpochMillis(yield* DateTime.now);
+    const value = yield* backend.get(stateKey(stateDigest)).pipe(Effect.mapError(() => readFailed));
+
+    if (value === undefined) {
+      return yield* InvalidOAuthState.make();
+    }
+
+    const row = yield* decodeStateRow(value).pipe(
+      Effect.mapError(() => AuthStoreError.make({ message: "Corrupt auth store row" })),
+    );
+
+    if (row.consumed || now >= DateTime.toEpochMillis(row.state.expiresAt)) {
+      return yield* InvalidOAuthState.make();
+    }
+
+    // The consumed tombstone (rather than a delete) is what makes replays of a
+    // captured callback URL fail deterministically until the row expires out.
+    const consumedRow = yield* encodeStateRow(
+      StoredOAuthState.make({ ...row, consumed: true }),
+    ).pipe(Effect.mapError(() => writeFailed));
+
+    yield* backend.put(stateKey(stateDigest), consumedRow).pipe(Effect.mapError(() => writeFailed));
+
+    return row.state;
+  });
+
+  return {
+    issue: (state: OAuthState) => serialized(issue(state)),
+    consume: (stateDigest: TokenDigest) => serialized(consume(stateDigest)),
+  };
+});
+
+/**
+ * Single-use persistence for pending authorization states. `consume` must be
+ * atomic: exactly one of concurrent consumptions of the same state may
+ * succeed, and every failure mode (unknown, expired, already consumed)
+ * collapses to `InvalidOAuthState`.
+ *
+ * Adapters implement the interface directly against a store with real
+ * transactions, or provide an `AuthStoreBackend` to `layerBackend` — the same
+ * backend the challenge/registration `AuthStore` uses; key namespaces are
+ * disjoint, so one backend can serve both.
+ */
+export class OAuthStateStore extends Context.Service<
+  OAuthStateStore,
+  {
+    readonly issue: (state: OAuthState) => Effect.Effect<void, AuthStoreError>;
+    /**
+     * Checks existence, expiry, and prior consumption as one atomic
+     * operation, then marks the state consumed.
+     */
+    readonly consume: (
+      stateDigest: TokenDigest,
+    ) => Effect.Effect<OAuthState, InvalidOAuthState | AuthStoreError>;
+  }
+>()("effect-auth/OAuthStateStore") {
+  /** The canonical state machine over whichever `AuthStoreBackend` is provided. */
+  static readonly layerBackend: Layer.Layer<OAuthStateStore, never, AuthStoreBackend> =
+    Layer.effect(OAuthStateStore)(makeBackendOAuthStateStore);
+
+  /** In-memory adapter for tests and local development; never durable. */
+  static readonly layerMemory: Layer.Layer<OAuthStateStore> = OAuthStateStore.layerBackend.pipe(
+    Layer.provide(AuthStoreBackend.layerMemory),
+  );
+}