@yielded/auth 0.1.0-beta.1

package/src/sessions/AuthenticationAuthority.ts

@@ -0,0 +1,51 @@
+import { Context, type DateTime, type Effect } from "effect";
+
+import type { PreparedCommit } from "../hooks/commit";
+import type { SubjectId } from "../Schema";
+import type { PrepareSessionCommit } from "./commit";
+import type {
+  PendingAuthenticationInvalid,
+  SessionUnavailable,
+  StaleAuthentication,
+} from "./errors";
+import type {
+  AuthenticationEvidence,
+  AuthenticationRequirement,
+  AuthenticationRevision,
+  PendingConsumption,
+} from "./models";
+
+/** Subject status, factor policy, and revision are owned by the consumer's identity authority. */
+export class AuthenticationAuthority extends Context.Service<
+  AuthenticationAuthority,
+  {
+    /** Before verification, read active subject + these independently resolved credential IDs. */
+    readonly capture: (
+      subjectId: SubjectId,
+      credentialIds: ReadonlyArray<string>,
+    ) => Effect.Effect<AuthenticationRevision, StaleAuthentication | SessionUnavailable>;
+    /** Reject unless the captured revision is still current; never refresh old evidence's revision. */
+    readonly requirements: (
+      evidence: AuthenticationEvidence,
+    ) => Effect.Effect<AuthenticationRequirement, StaleAuthentication | SessionUnavailable>;
+    /**
+     * Linearization point for fresh signed-session authentication. Check active
+     * subject, current factor policy/freshness, unexpired issuance, and exactly these revisions, consuming pending state in the same
+     * commit when provided. Re-read the clock at the conditional commit, never rely
+     * solely on the caller's pre-hook timestamp. Stateless verification and renewal never call this.
+     */
+    readonly approve: <A>(
+      input: {
+        readonly evidence: AuthenticationEvidence;
+        readonly now: DateTime.Utc;
+        readonly expiresAt: DateTime.Utc;
+        readonly absoluteExpiresAt: DateTime.Utc;
+        readonly pending?: PendingConsumption;
+      },
+      prepare: PrepareSessionCommit<void, A>,
+    ) => Effect.Effect<
+      PreparedCommit<A>,
+      StaleAuthentication | PendingAuthenticationInvalid | SessionUnavailable
+    >;
+  }
+>()("effect-auth/AuthenticationAuthority") {}

package/src/sessions/PendingAuthentication.ts

@@ -0,0 +1,121 @@
+import { DateTime, Effect, Schema } from "effect";
+
+import type { PreparedCommit } from "../hooks/commit";
+import { TokenDigest } from "../Schema";
+import type { PrepareSessionCommit } from "./commit";
+import {
+  PendingAuthenticationInvalid,
+  type SessionConflict,
+  type SessionUnavailable,
+  type StaleAuthentication,
+} from "./errors";
+import {
+  AuthenticationFlowId,
+  AuthenticationRevision,
+  type AuthenticationEvidence,
+  type SecurityRevision,
+} from "./models";
+
+export interface PendingAuthenticationState {
+  readonly digest: TokenDigest;
+  readonly version: SecurityRevision;
+  readonly evidence: AuthenticationEvidence;
+  readonly expiresAt: DateTime.Utc;
+  readonly attemptLimit: number;
+}
+
+export interface PendingAuthenticationRecord<Claims> extends PendingAuthenticationState {
+  readonly claims: Claims;
+}
+
+/** Internal correlation for an independently verified additional factor. This is
+ * neither a session nor reusable authorization; final completion rechecks it. */
+export const PendingAuthenticationContext = Schema.Struct({
+  flowId: AuthenticationFlowId,
+  bindingDigest: TokenDigest,
+  revision: AuthenticationRevision,
+  expiresAtMillis: Schema.Int,
+});
+
+export type PendingAuthenticationContext = typeof PendingAuthenticationContext.Type;
+
+/** Detaches the entire graph and projects away storage/private fields. */
+export const snapshotPendingAuthenticationContext = Effect.fn(
+  "snapshotPendingAuthenticationContext",
+)(function* (input: PendingAuthenticationContext) {
+  const value = yield* Schema.decodeEffect(PendingAuthenticationContext)(input).pipe(
+    Effect.mapError(() => PendingAuthenticationInvalid.make({})),
+  );
+
+  return Object.freeze({
+    flowId: value.flowId,
+    bindingDigest: value.bindingDigest,
+    expiresAtMillis: value.expiresAtMillis,
+    revision: Object.freeze({
+      subjectId: value.revision.subjectId,
+      securityRevision: value.revision.securityRevision,
+      credentials: Object.freeze(
+        value.revision.credentials.map((item) =>
+          Object.freeze({
+            credentialId: item.credentialId,
+            revision: item.revision,
+          }),
+        ),
+      ),
+    }),
+  });
+});
+
+export const pendingAuthenticationContext = (record: PendingAuthenticationState) =>
+  snapshotPendingAuthenticationContext({
+    flowId: record.evidence.flowId,
+    bindingDigest: record.evidence.bindingDigest,
+    revision: record.evidence.revision,
+    expiresAtMillis: DateTime.toEpochMillis(record.expiresAt),
+  });
+
+/** Optional MFA persistence; minimal single-factor sessions do not require this capability. */
+export interface PendingAuthentication<Claims> {
+  /** Authoritative non-consuming private-bearer lookup. Reject expired, consumed,
+   * exhausted, stale or inactive subject/credential state. Do not decode Claims.
+   * Locks end at this read; final completion must recheck after factor verification.
+   */
+  readonly context: (input: {
+    readonly digest: TokenDigest;
+    readonly now: DateTime.Utc;
+  }) => Effect.Effect<
+    PendingAuthenticationContext,
+    PendingAuthenticationInvalid | SessionUnavailable
+  >;
+
+  /** Conditional on active subject and original revisions, unique by initiating flow.
+   * Duplicate flow MUST fail SessionConflict. Interactive owners reject before
+   * prepare. Ordered-batch owners may prepare speculatively during a concurrent
+   * race, but MUST discard the losing receipt and events. Never return an existing
+   * record paired with this attempt's newly generated secret.
+   */
+  readonly create: <A>(
+    input: Omit<PendingAuthenticationRecord<Claims>, "version">,
+    now: DateTime.Utc,
+    prepare: PrepareSessionCommit<PendingAuthenticationRecord<Claims>, A>,
+  ) => Effect.Effect<PreparedCommit<A>, StaleAuthentication | SessionConflict | SessionUnavailable>;
+  /** Authoritative expiry, binding, revision, consumed status, and budget checks. */
+  readonly read: (input: {
+    readonly digest: TokenDigest;
+    readonly bindingDigest: TokenDigest;
+    readonly now: DateTime.Utc;
+  }) => Effect.Effect<
+    PendingAuthenticationRecord<Claims>,
+    PendingAuthenticationInvalid | SessionUnavailable
+  >;
+  /** Prepare a rejection VALUE; translate it to a public failure only after the root
+   * receipt commits, so outer rollback/error translation cannot erase attempts. */
+  readonly reject: <A>(
+    input: {
+      readonly digest: TokenDigest;
+      readonly bindingDigest: TokenDigest;
+      readonly now: DateTime.Utc;
+    },
+    prepare: PrepareSessionCommit<{ readonly _tag: "Rejected" }, A>,
+  ) => Effect.Effect<PreparedCommit<A>, SessionUnavailable>;
+}

package/src/sessions/SessionStepUpPersistence.ts

@@ -0,0 +1,164 @@
+import { type DateTime, type Effect, Schema } from "effect";
+
+import type { PreparedCommit } from "../hooks/commit";
+import { TokenDigest } from "../Schema";
+import type { PrepareSessionCommit } from "./commit";
+import type {
+  SessionConflict,
+  SessionStepUpInvalid,
+  SessionUnavailable,
+  StaleAuthentication,
+} from "./errors";
+import {
+  AuthenticationFlowId,
+  AuthenticationRequirement,
+  AuthenticationRevision,
+  AssuranceAlternative,
+  SecurityRevision,
+  SessionCredentialVersion,
+  SessionId,
+  type AuthenticationEvidence,
+  type SessionInspection,
+} from "./models";
+import type { PendingAuthenticationContext } from "./PendingAuthentication";
+
+export const SessionStepUpProfileId = Schema.String.check(
+  Schema.isPattern(/^[A-Za-z0-9._-]{1,128}$/),
+).pipe(Schema.brand("effect-auth/SessionStepUpProfileId"));
+
+export type SessionStepUpProfileId = typeof SessionStepUpProfileId.Type;
+
+export const SessionStepUpRequirement = Schema.Struct({
+  ...AuthenticationRequirement.fields,
+  alternatives: Schema.NonEmptyArray(
+    Schema.Struct({
+      ...AssuranceAlternative.fields,
+      factors: AssuranceAlternative.fields.factors.check(Schema.isMaxLength(3)),
+      minimumCredentials: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 64 })),
+    }),
+  ).check(Schema.isMaxLength(16)),
+});
+
+export const SessionStepUpProfile = Schema.Struct({
+  profileId: SessionStepUpProfileId,
+  generation: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER })),
+  requirement: SessionStepUpRequirement,
+  lifetimeMillis: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 900000 })),
+  attemptLimit: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 100 })),
+});
+
+export type SessionStepUpProfile = typeof SessionStepUpProfile.Type;
+
+export const StepUpPending = Schema.TaggedStruct("StepUpPending", {
+  profileId: SessionStepUpProfileId,
+  expiresAt: Schema.DateTimeUtcFromMillis,
+});
+
+export type StepUpPending = typeof StepUpPending.Type;
+
+export const SessionStepUpIntent = Schema.TaggedStruct("SessionStepUpIntent", {
+  digest: TokenDigest,
+  version: SecurityRevision,
+  flowId: AuthenticationFlowId,
+  bindingDigest: TokenDigest,
+  revision: AuthenticationRevision,
+  sourceKind: Schema.Literals(["Stateful", "StateAssistedSigned", "StatelessSigned"]),
+  sourceSessionId: SessionId,
+  sourceCredentialVersion: SessionCredentialVersion,
+  sourceAuthenticatedAt: Schema.DateTimeUtcFromMillis,
+  sourceExpiresAt: Schema.DateTimeUtcFromMillis,
+  sourceAbsoluteExpiresAt: Schema.DateTimeUtcFromMillis,
+  profileId: SessionStepUpProfileId,
+  profileGeneration: SessionStepUpProfile.fields.generation,
+  profileDigest: TokenDigest,
+  requirement: SessionStepUpProfile.fields.requirement,
+  expiresAt: Schema.DateTimeUtcFromMillis,
+  attemptLimit: SessionStepUpProfile.fields.attemptLimit,
+});
+
+export type SessionStepUpIntent = typeof SessionStepUpIntent.Type;
+
+/** Private guard from the SAME authoritative read as inspection. */
+export interface SessionStepUpSource<Claims> {
+  readonly inspection: SessionInspection<Claims>;
+  readonly guard:
+    | {
+        readonly _tag: "Stateful";
+        readonly digest: TokenDigest;
+        readonly rowVersion: SecurityRevision;
+      }
+    | { readonly _tag: "StateAssistedSigned" }
+    | { readonly _tag: "StatelessSigned" };
+}
+
+export type SessionStepUpReplacement<Claims> =
+  | {
+      readonly _tag: "Stateful";
+      readonly inspection: SessionInspection<Claims>;
+      readonly expectedDigest: TokenDigest;
+      readonly expectedRowVersion: SecurityRevision;
+      readonly nextDigest: TokenDigest;
+    }
+  | {
+      readonly _tag: "StateAssistedSigned";
+      readonly inspection: SessionInspection<Claims>;
+      readonly tombstoneSessionId: SessionId;
+      readonly tombstoneUntil: DateTime.Utc;
+    }
+  | { readonly _tag: "StatelessSigned"; readonly inspection: SessionInspection<Claims> };
+
+/** No bearer, callback or crypto work. All fields are preplanned under the core's
+ * trusted snapshots. Native owners must preserve the exact replacement metadata. */
+export interface SessionStepUpCompletionPlan<Claims> {
+  readonly intent: SessionStepUpIntent;
+  readonly source: SessionStepUpSource<Claims>;
+  readonly evidence: AuthenticationEvidence;
+  readonly baseRequirement: AuthenticationRequirement;
+  readonly profileRequirement: AuthenticationRequirement;
+  readonly now: DateTime.Utc;
+  readonly replacement: SessionStepUpReplacement<Claims>;
+}
+
+/** Optional, distinct from login pending. No implementation may compose standalone
+ * rotate/revoke/pending commits to approximate the one-owner complete transition. */
+export interface SessionStepUpPersistence<Claims> {
+  /** Check active exact revisions and all source/time bounds; unique flow/digest.
+   * Prepare BEFORE the actual commit. Ambient owners must join or reject before writes. */
+  readonly create: <A>(
+    input: Omit<SessionStepUpIntent, "version">,
+    now: DateTime.Utc,
+    prepare: PrepareSessionCommit<SessionStepUpIntent, A>,
+  ) => Effect.Effect<PreparedCommit<A>, StaleAuthentication | SessionConflict | SessionUnavailable>;
+  /** Claims-free authoritative kind/source/revision/expiry/consumed/budget checks. */
+  readonly context: (input: {
+    readonly digest: TokenDigest;
+    readonly now: DateTime.Utc;
+  }) => Effect.Effect<PendingAuthenticationContext, SessionStepUpInvalid | SessionUnavailable>;
+  readonly read: (input: {
+    readonly digest: TokenDigest;
+    readonly bindingDigest: TokenDigest;
+    readonly now: DateTime.Utc;
+  }) => Effect.Effect<SessionStepUpIntent, SessionStepUpInvalid | SessionUnavailable>;
+  /** Authenticate binding internally, atomically cap/increment attempts, return a
+   * decision VALUE. Unknown commits are unavailable, never automatically retried. */
+  readonly reject: <A>(
+    input: { readonly digest: TokenDigest; readonly now: DateTime.Utc },
+    prepare: PrepareSessionCommit<{ readonly _tag: "Rejected" }, A>,
+  ) => Effect.Effect<PreparedCommit<A>, SessionUnavailable>;
+  /** Recheck intent version/status/budget, exact source/profile/revisions and BOTH
+   * requirements at the actual commit clock. Stateful: guard source digest/row and
+   * credential versions, update in place + consume. Stored sourceKind must match
+   * both the inspected guard and replacement tag, including after deployment changes. Assisted: insert absent source
+   * lineage tombstone + consume. Pure signed: consume only; old source remains live.
+   * Preserve source authenticatedAt/absolute expiry and exact prepared metadata.
+   * A guard loss discards prepared bearer/events, including under an outer owner.
+   * The callback is synchronous and must run before physical commit, including D1.
+   */
+  readonly complete: <A>(
+    plan: SessionStepUpCompletionPlan<Claims>,
+    prepare: PrepareSessionCommit<SessionInspection<Claims>, A>,
+  ) => Effect.Effect<
+    PreparedCommit<A>,
+    SessionStepUpInvalid | StaleAuthentication | SessionConflict | SessionUnavailable
+  >;
+}

package/src/sessions/assurance.ts

@@ -0,0 +1,192 @@
+import { Array, DateTime, Effect, Schema } from "effect";
+
+import { AuthenticationAssurance } from "../operations/context";
+import {
+  PendingAuthenticationInvalid,
+  SessionConfigurationError,
+  StaleAuthentication,
+} from "./errors";
+import {
+  AuthenticationEvidence,
+  AuthenticationRequirement,
+  SessionAuthenticationProvenance,
+} from "./models";
+
+const evidenceCodec = Schema.toCodecIso(AuthenticationEvidence);
+
+export const snapshotAuthenticationEvidence = Effect.fn("snapshotAuthenticationEvidence")(
+  function* (evidence: AuthenticationEvidence) {
+    // Bound Type input before schema projection allocates a detached proof graph.
+    if (evidence.proofs.length > 64 || evidence.revision.credentials.length > 64)
+      return yield* StaleAuthentication.make({});
+
+    const projected = yield* Schema.encodeEffect(evidenceCodec)(evidence).pipe(
+      Effect.flatMap(Schema.decodeEffect(evidenceCodec)),
+      Effect.mapError(() => StaleAuthentication.make({})),
+    );
+
+    return Object.freeze({
+      ...projected,
+      revision: Object.freeze({
+        ...projected.revision,
+        credentials: Object.freeze(
+          projected.revision.credentials.map((item) => Object.freeze({ ...item })),
+        ),
+      }),
+      proofs: Object.freeze(
+        Array.map(projected.proofs, (proof) => {
+          const verifiedAt = DateTime.makeUnsafe(DateTime.toEpochMillis(proof.verifiedAt));
+
+          // DateTime.Utc caches parts lazily; populate before freezing the detached instant.
+          Object.freeze(DateTime.toPartsUtc(verifiedAt));
+          Object.freeze(verifiedAt);
+
+          return Object.freeze({
+            ...proof,
+            factors: Object.freeze([...proof.factors]),
+            verifiedAt,
+          });
+        }),
+      ),
+    });
+  },
+);
+
+export const snapshotSessionAuthenticationProvenance = Effect.fn(
+  "snapshotSessionAuthenticationProvenance",
+)(function* (input: SessionAuthenticationProvenance) {
+  if (input?.evidence?.proofs?.length > 64 || input?.evidence?.revision?.credentials?.length > 64)
+    return yield* StaleAuthentication.make({});
+  yield* Schema.decodeEffect(Schema.toType(SessionAuthenticationProvenance))(input).pipe(
+    Effect.mapError(() => StaleAuthentication.make({})),
+  );
+  const ids = new Set(input.evidence.revision.credentials.map((item) => item.credentialId));
+
+  if (
+    ids.size !== input.evidence.revision.credentials.length ||
+    input.evidence.proofs.some((proof) => !ids.has(proof.credentialId))
+  )
+    return yield* StaleAuthentication.make({});
+
+  return Object.freeze({ evidence: yield* snapshotAuthenticationEvidence(input.evidence) });
+});
+
+export const assessAuthentication = Effect.fn("assessAuthentication")(function* (
+  input: AuthenticationEvidence,
+  configured: AuthenticationRequirement,
+) {
+  if (input.proofs.length > 64 || input.revision.credentials.length > 64)
+    return yield* StaleAuthentication.make({});
+
+  const evidence = yield* Schema.decodeEffect(Schema.toType(AuthenticationEvidence))(input).pipe(
+    Effect.mapError(() => StaleAuthentication.make({})),
+  );
+
+  const requirement = yield* Schema.decodeEffect(AuthenticationRequirement)(configured).pipe(
+    Effect.mapError(() => SessionConfigurationError.make({ reason: "pending-authentication" })),
+  );
+
+  const revisions = new Map<string, string>();
+
+  for (const revision of evidence.revision.credentials) {
+    if (revisions.has(revision.credentialId)) return yield* StaleAuthentication.make({});
+    revisions.set(revision.credentialId, revision.revision);
+  }
+  if (evidence.proofs.some((proof) => !revisions.has(proof.credentialId)))
+    return yield* StaleAuthentication.make({});
+  const now = DateTime.toEpochMillis(yield* DateTime.now);
+
+  for (const proof of evidence.proofs) {
+    const age = now - DateTime.toEpochMillis(proof.verifiedAt);
+
+    if (age < 0) return yield* StaleAuthentication.make({});
+  }
+
+  const fresh = evidence.proofs.filter(
+    (proof) => now - DateTime.toEpochMillis(proof.verifiedAt) < requirement.maximumAgeMillis,
+  );
+
+  if (fresh.length === 0) return yield* StaleAuthentication.make({});
+  const factors = [...new Set(fresh.flatMap((proof) => proof.factors))];
+  const credentials = new Set(fresh.map((proof) => proof.credentialId));
+
+  const satisfied = requirement.alternatives.some(
+    (alternative) =>
+      alternative.factors.every((factor) => factors.includes(factor)) &&
+      credentials.size >= alternative.minimumCredentials &&
+      fresh.some(
+        (proof) =>
+          (!alternative.userVerified || proof.userVerified) &&
+          (!alternative.phishingResistant || proof.phishingResistant),
+      ),
+  );
+
+  const first = fresh[0];
+
+  const authenticatedAt = fresh.reduce(
+    (oldest, proof) =>
+      DateTime.toEpochMillis(proof.verifiedAt) < DateTime.toEpochMillis(oldest)
+        ? proof.verifiedAt
+        : oldest,
+    first.verifiedAt,
+  );
+
+  const ordinals = new Map<string, number>();
+
+  for (const proof of evidence.proofs) {
+    if (!ordinals.has(proof.credentialId)) ordinals.set(proof.credentialId, ordinals.size);
+  }
+  if (ordinals.size > 64) return yield* StaleAuthentication.make({});
+
+  return {
+    satisfied,
+    assurance: AuthenticationAssurance.make({
+      method: first.method,
+      factors,
+      authenticatedAt,
+      evidence: Array.map(
+        evidence.proofs,
+        ({ method, credentialId, factors, userVerified, phishingResistant, verifiedAt }) => ({
+          method,
+          credentialOrdinal: ordinals.get(credentialId)!,
+          factors,
+          userVerified,
+          phishingResistant,
+          verifiedAt,
+        }),
+      ),
+    }),
+  };
+});
+
+/** Never refresh original proof timestamps or the revision captured before primary verification. */
+export const combineAuthenticationEvidence = (
+  original: AuthenticationEvidence,
+  additional: AuthenticationEvidence,
+): Effect.Effect<AuthenticationEvidence, PendingAuthenticationInvalid> => {
+  if (
+    original.flowId !== additional.flowId ||
+    original.bindingDigest !== additional.bindingDigest ||
+    original.revision.subjectId !== additional.revision.subjectId ||
+    original.revision.securityRevision !== additional.revision.securityRevision
+  )
+    return Effect.fail(PendingAuthenticationInvalid.make({}));
+
+  const revisions = new Map(
+    original.revision.credentials.map((credential) => [credential.credentialId, credential]),
+  );
+
+  for (const credential of additional.revision.credentials) {
+    const previous = revisions.get(credential.credentialId);
+
+    if (previous !== undefined && previous.revision !== credential.revision)
+      return Effect.fail(PendingAuthenticationInvalid.make({}));
+    revisions.set(credential.credentialId, credential);
+  }
+
+  return Effect.succeed({
+    ...original,
+    revision: { ...original.revision, credentials: [...revisions.values()] },
+    proofs: [...original.proofs, ...additional.proofs],
+  });
+};

package/src/sessions/commit.ts

@@ -0,0 +1,13 @@
+import type { CommitJournal, PreparedCommit } from "../hooks/commit";
+
+/**
+ * Runs inside the persistence adapter's actual commit journal. It can only prepare
+ * an immutable result/event; all cryptography and before hooks run beforehand.
+ * Interactive/savepoint owners reuse the outer journal, synchronous owners never
+ * suspend, and batch owners allocate final IDs/versions and prepare BEFORE executing the batch.
+ * No adapter may invoke this after its physical root commit has returned.
+ */
+export type PrepareSessionCommit<Record, A> = (
+  record: Record,
+  journal: CommitJournal,
+) => PreparedCommit<A>;

package/src/sessions/configuration.ts

@@ -0,0 +1,133 @@
+import { Duration, Layer, type Schema, type Scope } from "effect";
+
+import { cryptoLayer, hooksLayer } from "../auth/defaults";
+import type { SessionSigningKeyring } from "./crypto";
+import { SessionConfigurationError } from "./errors";
+import type { makeSessionModule, ModuleService } from "./module";
+import type { SessionPolicy } from "./policy";
+
+export interface SessionOptions {
+  readonly idleTimeout?: Duration.Input;
+  readonly maxAge?: Duration.Input;
+  readonly renewAfter?: Duration.Input;
+  readonly issuer?: string;
+  readonly audience?: string;
+  readonly generation?: number;
+  /** Retain the greatest maxAge of still-usable issued tokens after reducing policy. */
+  readonly maximumIssuedAge?: Duration.Input;
+  readonly maximumTokenBytes?: number;
+}
+
+export interface StatefulConfiguration {
+  readonly mode: "stateful";
+  readonly policy: (namespace: string) => SessionPolicy;
+}
+
+export interface StatelessConfiguration {
+  readonly mode: "stateless";
+  readonly policy: (namespace: string) => SessionPolicy;
+  readonly keys: SessionSigningKeyring;
+}
+
+export interface StateAssistedConfiguration {
+  readonly mode: "state-assisted";
+  readonly policy: (namespace: string) => SessionPolicy;
+  readonly keys: SessionSigningKeyring;
+}
+
+export type SessionConfiguration =
+  | StatefulConfiguration
+  | StatelessConfiguration
+  | StateAssistedConfiguration;
+
+const policy = (options: SessionOptions, immediate: boolean) => {
+  let values: Omit<SessionPolicy, "issuer" | "audience">;
+
+  try {
+    const maxAge = Duration.toMillis(options.maxAge ?? "30 days");
+
+    const idle = Duration.toMillis(
+      options.idleTimeout ?? Math.min(maxAge, Duration.toMillis("7 days")),
+    );
+
+    values = Object.freeze({
+      generation: options.generation ?? 1,
+      idleLifetimeMillis: idle,
+      absoluteLifetimeMillis: maxAge,
+      renewalIntervalMillis: Duration.toMillis(
+        options.renewAfter ?? Math.min(Math.floor(idle / 2), Duration.toMillis("1 day")),
+      ),
+      maximumIssuedAbsoluteLifetimeMillis: Duration.toMillis(options.maximumIssuedAge ?? maxAge),
+      maximumTokenBytes: options.maximumTokenBytes ?? 4096,
+      requireImmediateInvalidation: immediate,
+    });
+  } catch {
+    throw SessionConfigurationError.make({ reason: "policy" });
+  }
+  const issuer = options.issuer;
+  const audience = options.audience;
+
+  return (namespace: string): SessionPolicy => ({
+    ...values,
+    issuer: issuer ?? namespace,
+    audience: audience ?? namespace,
+  });
+};
+
+/** Authoritative sessions with immediate revocation; supply the bound persistence services. */
+export const stateful = (options: SessionOptions = {}): StatefulConfiguration =>
+  Object.freeze({ mode: "stateful", policy: policy(options, true) });
+
+/** Database-free verification. Sign-out clears this client's credential only. */
+export const stateless = (
+  options: SessionOptions & { readonly keys: SessionSigningKeyring },
+): StatelessConfiguration =>
+  Object.freeze({ mode: "stateless", policy: policy(options, false), keys: options.keys });
+
+/** Signed credentials checked against application-owned validity state. */
+export const stateAssisted = (
+  options: SessionOptions & { readonly keys: SessionSigningKeyring },
+): StateAssistedConfiguration =>
+  Object.freeze({ mode: "state-assisted", policy: policy(options, true), keys: options.keys });
+
+export type SessionRequirements<C, Id extends string, Claims extends Schema.Top> =
+  | Exclude<Claims["DecodingServices"] | Claims["EncodingServices"], Scope.Scope>
+  | (C extends StatefulConfiguration
+      ?
+          | ModuleService<Id, "persistence", Claims["Type"]>
+          | ModuleService<Id, "repository", Claims["Type"]>
+      : C extends StateAssistedConfiguration
+        ? ModuleService<Id, "validity", Claims["Type"]>
+        : never);
+
+export const configuredLayer = <
+  const Id extends string,
+  Claims extends Schema.Codec<unknown, unknown, unknown, unknown>,
+  C extends SessionConfiguration,
+>(
+  sessions: ReturnType<typeof makeSessionModule<Id, Claims>>,
+  configuration: C,
+): Layer.Layer<
+  ModuleService<Id, "strategy", Claims["Type"]>,
+  SessionConfigurationError,
+  SessionRequirements<C, Id, Claims>
+> => {
+  const configured = configuration.policy(sessions.moduleId);
+
+  const defaults = <A, E, R>(layer: Layer.Layer<A, E, R>) =>
+    layer.pipe(Layer.provide([cryptoLayer, hooksLayer]));
+
+  const layer =
+    configuration.mode === "stateful"
+      ? defaults(sessions.statefulLayer(configured))
+      : configuration.mode === "stateless"
+        ? defaults(sessions.statelessLayer(configured, configuration.keys))
+        : defaults(sessions.stateAssistedLayer(configured, configuration.keys));
+
+  // The selected mode determines exactly which persistence port the layer acquires.
+  return layer as Layer.Layer<
+    ModuleService<Id, "strategy", Claims["Type"]>,
+    SessionConfigurationError,
+    SessionRequirements<C, Id, Claims>
+  >;
+};