@yielded/auth 0.1.0-beta.1

package/src/identity/ExternalIdentityMutation.ts

@@ -0,0 +1,18 @@
+import { Context, type Effect } from "effect";
+
+import type { SubjectId } from "../Schema";
+import type { ExternalIdentity, IdentityConflict, IdentityUnavailable } from "./models";
+
+/**
+ * Binds a provider subject to an application subject. The authoritative store
+ * enforces uniqueness of the full provider, issuer and external-subject tuple.
+ */
+export class ExternalIdentityMutation extends Context.Service<
+  ExternalIdentityMutation,
+  {
+    readonly bind: (
+      subjectId: SubjectId,
+      identity: ExternalIdentity,
+    ) => Effect.Effect<void, IdentityConflict | IdentityUnavailable>;
+  }
+>()("effect-auth/ExternalIdentityMutation") {}

package/src/identity/IdentityMutation.ts

@@ -0,0 +1,41 @@
+import { Context, type Effect } from "effect";
+
+import type { SubjectId } from "../Schema";
+import type {
+  CredentialId,
+  IdentityConflict,
+  IdentityUnavailable,
+  LastSignInMethod,
+  LoginIdentifier,
+  SubjectInactive,
+} from "./models";
+
+/**
+ * Narrow removal capability. The authoritative adapter checks active status,
+ * ownership and the remaining usable sign-in methods in the SAME atomic write.
+ * A read/count followed by deletion is insufficient under concurrent removals.
+ * Removing a credential also removes its retained secrets and dependent proofs.
+ * Identifier removal/rebinding/verification changes that invalidate captured login
+ * authority MUST atomically bump subject securityRevision. AuthenticationRevision
+ * deliberately has no identifier-binding revision: deleting dependent proofs alone
+ * cannot invalidate password evidence already captured before verification.
+ */
+export class IdentityMutation extends Context.Service<
+  IdentityMutation,
+  {
+    readonly removeIdentifier: (
+      subjectId: SubjectId,
+      identifier: LoginIdentifier,
+    ) => Effect.Effect<
+      void,
+      IdentityConflict | LastSignInMethod | SubjectInactive | IdentityUnavailable
+    >;
+    readonly removeCredential: (
+      subjectId: SubjectId,
+      credentialId: CredentialId,
+    ) => Effect.Effect<
+      void,
+      IdentityConflict | LastSignInMethod | SubjectInactive | IdentityUnavailable
+    >;
+  }
+>()("effect-auth/IdentityMutation") {}

package/src/identity/IdentityRepository.ts

@@ -0,0 +1,37 @@
+import { Context, type Effect, type Option } from "effect";
+
+import type { SubjectId } from "../Schema";
+import type {
+  CredentialSummary,
+  ExternalIdentity,
+  IdentifierBinding,
+  IdentityUnavailable,
+  LoginIdentifier,
+  SubjectSnapshot,
+} from "./models";
+
+/**
+ * Application identity queries. No profile fields, email requirement, table
+ * layout, or account-creation side effect is implied by resolving an identity.
+ */
+export class IdentityRepository extends Context.Service<
+  IdentityRepository,
+  {
+    readonly findSubject: (
+      subjectId: SubjectId,
+    ) => Effect.Effect<Option.Option<SubjectSnapshot>, IdentityUnavailable>;
+    readonly findIdentifier: (
+      identifier: LoginIdentifier,
+    ) => Effect.Effect<Option.Option<IdentifierBinding>, IdentityUnavailable>;
+    /** Resolve the full configured provider + issuer + external subject tuple. */
+    readonly findExternalIdentity: (
+      identity: ExternalIdentity,
+    ) => Effect.Effect<Option.Option<SubjectId>, IdentityUnavailable>;
+    readonly listIdentifiers: (
+      subjectId: SubjectId,
+    ) => Effect.Effect<ReadonlyArray<IdentifierBinding>, IdentityUnavailable>;
+    readonly listCredentials: (
+      subjectId: SubjectId,
+    ) => Effect.Effect<ReadonlyArray<CredentialSummary>, IdentityUnavailable>;
+  }
+>()("effect-auth/IdentityRepository") {}

package/src/identity/SubjectLifecycle.ts

@@ -0,0 +1,80 @@
+import { Context, type Effect, Schema } from "effect";
+
+import { SubjectId } from "../Schema";
+import { type IdentityUnavailable, RecoveryReference } from "./models";
+
+export class InvalidationUnsupported extends Schema.TaggedError<InvalidationUnsupported>()(
+  "InvalidationUnsupported",
+  {},
+) {}
+
+/** No issued bearer remains valid for this subject after the commit. */
+export class ImmediatelyInvalidated extends Schema.TaggedClass<ImmediatelyInvalidated>()(
+  "ImmediatelyInvalidated",
+  {},
+) {}
+
+/**
+ * Pure stateless verification may accept old tokens until this instant. The
+ * adapter must prevent fresh primary authentication. Any stateless renewal of
+ * an existing token must remain bounded by this same instant, not extend it.
+ */
+export class ExpiresBy extends Schema.TaggedClass<ExpiresBy>()("ExpiresBy", {
+  instant: Schema.DateTimeUtcFromMillis,
+}) {}
+
+export const SubjectInvalidation = Schema.Union([ImmediatelyInvalidated, ExpiresBy]);
+
+export class SubjectCleanupComplete extends Schema.TaggedClass<SubjectCleanupComplete>()(
+  "SubjectCleanupComplete",
+  { subjectId: SubjectId, invalidation: SubjectInvalidation },
+) {}
+
+/**
+ * The account is already blocked from new auth, but retained material in another
+ * authority still needs cleanup. The consumer retries using recoveryReference.
+ */
+export class SubjectCleanupPending extends Schema.TaggedClass<SubjectCleanupPending>()(
+  "SubjectCleanupPending",
+  {
+    subjectId: SubjectId,
+    invalidation: SubjectInvalidation,
+    recoveryReference: RecoveryReference,
+  },
+) {}
+
+export const SubjectCleanupResult = Schema.Union([SubjectCleanupComplete, SubjectCleanupPending]);
+
+export interface SubjectTerminationInput {
+  readonly subjectId: SubjectId;
+  readonly requestId: string;
+  readonly invalidation: "immediate" | "allow-expiry";
+}
+
+/**
+ * Consumer-selected coordination of account disable/delete, credential and
+ * proof cleanup, external token cleanup, and the session strategy's invalidation.
+ * Workspace membership, profile and billing data remain application-owned.
+ *
+ * Operations are idempotent by requestId. Validate requested invalidation before
+ * writes; a stateless composition must reject `immediate` unless the consumer
+ * provides state-assisted validity. No implementation may return Complete while
+ * enabled credential/proof/token stores still permit future authentication.
+ */
+export class SubjectLifecycle extends Context.Service<
+  SubjectLifecycle,
+  {
+    readonly disable: (
+      input: SubjectTerminationInput,
+    ) => Effect.Effect<
+      typeof SubjectCleanupResult.Type,
+      InvalidationUnsupported | IdentityUnavailable
+    >;
+    readonly delete: (
+      input: SubjectTerminationInput,
+    ) => Effect.Effect<
+      typeof SubjectCleanupResult.Type,
+      InvalidationUnsupported | IdentityUnavailable
+    >;
+  }
+>()("effect-auth/SubjectLifecycle") {}

package/src/identity/SubjectProvisioner.ts

@@ -0,0 +1,40 @@
+import { Context, type DateTime, type Effect } from "effect";
+
+import type {
+  IdentityConflict,
+  IdentityUnavailable,
+  LoginIdentifier,
+  ProvisioningResult,
+} from "./models";
+
+/**
+ * Trusted method input after its registration proof/policy has been checked.
+ * This is a service input, never a remotely exposed registration payload.
+ * Omit verifiedAt for password-only registration with an unverified identifier.
+ */
+export type SubjectProvisioningInput = { readonly requestId: string } & (
+  | { readonly identifier?: never; readonly verifiedAt?: never }
+  | { readonly identifier: LoginIdentifier; readonly verifiedAt?: DateTime.Utc }
+);
+
+/**
+ * Application authority for subject creation and initial identifier binding.
+ *
+ * Repeating a requestId with the same input must resolve the same subject;
+ * repeating it with different input must fail. Identifier uniqueness and
+ * provisioning commit together when they share an authority. Cross-authority
+ * implementations return ProvisioningPending until reconciliation is complete,
+ * never an authenticated result for a partially provisioned account.
+ *
+ * This port does not create a session or bind method-specific credentials. The
+ * method's registration coordinator owns that atomic boundary (or exposes its
+ * pending recovery outcome) before it can issue an authenticated result.
+ */
+export class SubjectProvisioner extends Context.Service<
+  SubjectProvisioner,
+  {
+    readonly provision: (
+      input: SubjectProvisioningInput,
+    ) => Effect.Effect<ProvisioningResult, IdentityConflict | IdentityUnavailable>;
+  }
+>()("effect-auth/SubjectProvisioner") {}

package/src/identity/codecs.ts

@@ -0,0 +1,54 @@
+import { Effect, Schema } from "effect";
+
+import { SubjectId } from "../Schema";
+
+/** Adapter failures deliberately omit the native key and rejected wire input. */
+export class IdentityCodecError extends Schema.TaggedError<IdentityCodecError>()(
+  "IdentityCodecError",
+  { reason: Schema.Literals(["invalid-key", "lossy-key"]) },
+) {}
+
+/**
+ * A consumer's native key remains native in its database. Only the auth boundary
+ * uses SubjectId. Neither direction may silently normalize or truncate a key.
+ * ID generation belongs to the consumer, including database-generated keys.
+ */
+export const subjectIdCodec = <A>(schema: Schema.Codec<A, string>) => {
+  const decode = Schema.decodeEffect(schema);
+  const encode = Schema.encodeEffect(schema);
+  const decodeSubject = Schema.decodeEffect(SubjectId);
+  const equivalent = Schema.toEquivalence(schema);
+  const invalid = () => IdentityCodecError.make({ reason: "invalid-key" });
+
+  return {
+    toNative: Effect.fn("subjectIdCodec.toNative")(function* (subjectId: SubjectId) {
+      const native = yield* decode(subjectId).pipe(Effect.mapError(invalid));
+      const roundTrip = yield* encode(native).pipe(Effect.mapError(invalid));
+
+      if (roundTrip !== subjectId) {
+        return yield* IdentityCodecError.make({ reason: "lossy-key" });
+      }
+
+      return native;
+    }),
+    toSubject: Effect.fn("subjectIdCodec.toSubject")(function* (native: A) {
+      const wire = yield* encode(native).pipe(Effect.mapError(invalid));
+      const roundTrip = yield* decode(wire).pipe(Effect.mapError(invalid));
+
+      if (!equivalent(native, roundTrip)) {
+        return yield* IdentityCodecError.make({ reason: "lossy-key" });
+      }
+
+      return yield* decodeSubject(wire).pipe(Effect.mapError(invalid));
+    }),
+  } as const;
+};
+
+/** Keeps the consumer's UUID version, spelling, and database column unchanged. */
+export const stringSubjectId = subjectIdCodec(Schema.NonEmptyString);
+
+/** Rejects unsafe JS integers and noncanonical aliases such as `01` and `1e2`. */
+export const numericSubjectId = subjectIdCodec(Schema.FiniteFromString.check(Schema.isInt()));
+
+/** Use for SQL bigint keys that exceed JavaScript's safe integer range. */
+export const bigintSubjectId = subjectIdCodec(Schema.BigIntFromString);

package/src/identity/models.ts

@@ -0,0 +1,82 @@
+import { Schema } from "effect";
+
+import { SubjectId } from "../Schema";
+
+/** Namespace and normalization are supplied by the method/consumer, not email. */
+export class LoginIdentifier extends Schema.Class<LoginIdentifier>("effect-auth/LoginIdentifier")({
+  namespace: Schema.NonEmptyString,
+  value: Schema.NonEmptyString,
+}) {}
+
+/** Stable provider identity. Matching profile email addresses do not imply a link. */
+export class ExternalIdentity extends Schema.Class<ExternalIdentity>(
+  "effect-auth/ExternalIdentity",
+)({
+  provider: Schema.NonEmptyString,
+  issuer: Schema.NonEmptyString,
+  subject: Schema.NonEmptyString,
+}) {}
+
+/** A non-secret reference; never a bearer credential or a recovery code. */
+export const CredentialId = Schema.NonEmptyString.pipe(Schema.brand("effect-auth/CredentialId"));
+export type CredentialId = typeof CredentialId.Type;
+
+export class IdentifierBinding extends Schema.Class<IdentifierBinding>(
+  "effect-auth/IdentifierBinding",
+)({
+  identifier: LoginIdentifier,
+  subjectId: SubjectId,
+  verifiedAt: Schema.Option(Schema.DateTimeUtcFromMillis),
+}) {}
+
+export class CredentialSummary extends Schema.Class<CredentialSummary>(
+  "effect-auth/CredentialSummary",
+)({
+  id: CredentialId,
+  method: Schema.NonEmptyString,
+  createdAt: Schema.DateTimeUtcFromMillis,
+  /** A second factor by itself must not count as a remaining sign-in method. */
+  usableForSignIn: Schema.Boolean,
+}) {}
+
+export class SubjectSnapshot extends Schema.Class<SubjectSnapshot>("effect-auth/SubjectSnapshot")({
+  subjectId: SubjectId,
+  status: Schema.Literals(["active", "disabled", "deleting"]),
+}) {}
+
+/** Consumer-owned reconciliation key; not a token that grants authentication. */
+export const RecoveryReference = Schema.NonEmptyString.pipe(
+  Schema.brand("effect-auth/RecoveryReference"),
+);
+
+export class SubjectProvisioned extends Schema.TaggedClass<SubjectProvisioned>()(
+  "SubjectProvisioned",
+  { subjectId: SubjectId },
+) {}
+
+/** No session may be issued until the consumer resolves this outcome. */
+export class ProvisioningPending extends Schema.TaggedClass<ProvisioningPending>()(
+  "ProvisioningPending",
+  { recoveryReference: RecoveryReference },
+) {}
+
+export const ProvisioningResult = Schema.Union([SubjectProvisioned, ProvisioningPending]);
+export type ProvisioningResult = typeof ProvisioningResult.Type;
+
+/** Expected identity failures contain no identifier value or database diagnostics. */
+export class IdentityConflict extends Schema.TaggedError<IdentityConflict>()(
+  "IdentityConflict",
+  {},
+) {}
+
+export class IdentityUnavailable extends Schema.TaggedError<IdentityUnavailable>()(
+  "IdentityUnavailable",
+  {},
+) {}
+
+export class LastSignInMethod extends Schema.TaggedError<LastSignInMethod>()(
+  "LastSignInMethod",
+  {},
+) {}
+
+export class SubjectInactive extends Schema.TaggedError<SubjectInactive>()("SubjectInactive", {}) {}

package/src/identity/operations.ts

@@ -0,0 +1,182 @@
+import { Effect, Layer, Option, Schema } from "effect";
+
+import {
+  type AssuranceRequirement,
+  requireAssurance,
+  requireAuthenticated,
+} from "../operations/context";
+import { makeOperation } from "../operations/operation";
+import { SubjectId } from "../Schema";
+import { IdentityMutation } from "./IdentityMutation";
+import { IdentityRepository } from "./IdentityRepository";
+import {
+  CredentialId,
+  CredentialSummary,
+  IdentifierBinding,
+  IdentityConflict,
+  IdentityUnavailable,
+  LastSignInMethod,
+  LoginIdentifier,
+  SubjectInactive,
+  SubjectSnapshot,
+} from "./models";
+import {
+  InvalidationUnsupported,
+  SubjectCleanupResult,
+  SubjectLifecycle,
+} from "./SubjectLifecycle";
+
+const activeSubject = Effect.fn("IdentityOperations.activeSubject")(function* (
+  subjectId: SubjectId,
+) {
+  const repository = yield* IdentityRepository;
+  const subject = yield* repository.findSubject(subjectId);
+
+  if (Option.isNone(subject) || subject.value.status !== "active") {
+    return yield* SubjectInactive.make();
+  }
+
+  return subject.value;
+});
+
+export const InspectIdentity = makeOperation("identity.inspect", {
+  payload: Schema.Void,
+  success: SubjectSnapshot,
+  error: Schema.Union([SubjectInactive, IdentityUnavailable]),
+  access: "authenticated",
+  exposure: "public",
+  replay: "read-only",
+});
+
+export const ListIdentifiers = makeOperation("identity.listIdentifiers", {
+  payload: Schema.Void,
+  success: Schema.Array(IdentifierBinding),
+  error: Schema.Union([SubjectInactive, IdentityUnavailable]),
+  access: "authenticated",
+  exposure: "public",
+  replay: "read-only",
+});
+
+export const ListCredentials = makeOperation("identity.listCredentials", {
+  payload: Schema.Void,
+  success: Schema.Array(CredentialSummary),
+  error: Schema.Union([SubjectInactive, IdentityUnavailable]),
+  access: "authenticated",
+  exposure: "public",
+  replay: "read-only",
+});
+
+export const identityQueryLayer = Layer.mergeAll(
+  InspectIdentity.handlerLayer(
+    Effect.fn("IdentityOperations.inspect")(function* (_, context) {
+      const caller = yield* requireAuthenticated(context);
+
+      return yield* activeSubject(caller.subjectId);
+    }),
+  ),
+  ListIdentifiers.handlerLayer(
+    Effect.fn("IdentityOperations.listIdentifiers")(function* (_, context) {
+      const caller = yield* requireAuthenticated(context);
+      const repository = yield* IdentityRepository;
+
+      yield* activeSubject(caller.subjectId);
+
+      return yield* repository.listIdentifiers(caller.subjectId);
+    }),
+  ),
+  ListCredentials.handlerLayer(
+    Effect.fn("IdentityOperations.listCredentials")(function* (_, context) {
+      const caller = yield* requireAuthenticated(context);
+      const repository = yield* IdentityRepository;
+
+      yield* activeSubject(caller.subjectId);
+
+      return yield* repository.listCredentials(caller.subjectId);
+    }),
+  ),
+);
+
+/** Configure the method/factor policy at the consumer's Layer composition boundary. */
+export const makeIdentityChanges = (assurance: AssuranceRequirement) => {
+  const RemoveIdentifier = makeOperation("identity.removeIdentifier", {
+    payload: Schema.Struct({ identifier: LoginIdentifier }),
+    success: Schema.Void,
+    error: Schema.Union([IdentityConflict, LastSignInMethod, SubjectInactive, IdentityUnavailable]),
+    access: "authenticated",
+    exposure: "public",
+    replay: "non-idempotent",
+    authorize: (_, context) => requireAssurance(context, assurance).pipe(Effect.asVoid),
+  });
+
+  const RemoveCredential = makeOperation("identity.removeCredential", {
+    payload: Schema.Struct({ credentialId: CredentialId }),
+    success: Schema.Void,
+    error: Schema.Union([IdentityConflict, LastSignInMethod, SubjectInactive, IdentityUnavailable]),
+    access: "authenticated",
+    exposure: "public",
+    replay: "non-idempotent",
+    authorize: (_, context) => requireAssurance(context, assurance).pipe(Effect.asVoid),
+  });
+
+  const layer = Layer.mergeAll(
+    RemoveIdentifier.handlerLayer(
+      Effect.fn("IdentityOperations.removeIdentifier")(function* (payload, context) {
+        const caller = yield* requireAuthenticated(context);
+        const mutation = yield* IdentityMutation;
+
+        yield* mutation.removeIdentifier(caller.subjectId, payload.identifier);
+      }),
+    ),
+    RemoveCredential.handlerLayer(
+      Effect.fn("IdentityOperations.removeCredential")(function* (payload, context) {
+        const caller = yield* requireAuthenticated(context);
+        const mutation = yield* IdentityMutation;
+
+        yield* mutation.removeCredential(caller.subjectId, payload.credentialId);
+      }),
+    ),
+  );
+
+  return { RemoveIdentifier, RemoveCredential, layer } as const;
+};
+
+const terminationPayload = Schema.Struct({
+  subjectId: SubjectId,
+  requestId: Schema.NonEmptyString,
+  invalidation: Schema.Literals(["immediate", "allow-expiry"]),
+});
+
+/** System operations have contracts without being implicitly network-exposed. */
+export const DisableSubject = makeOperation("identity.disableSubject", {
+  payload: terminationPayload,
+  success: SubjectCleanupResult,
+  error: Schema.Union([InvalidationUnsupported, IdentityUnavailable]),
+  access: "system",
+  replay: "idempotent",
+});
+
+export const DeleteSubject = makeOperation("identity.deleteSubject", {
+  payload: terminationPayload,
+  success: SubjectCleanupResult,
+  error: Schema.Union([InvalidationUnsupported, IdentityUnavailable]),
+  access: "system",
+  replay: "idempotent",
+});
+
+/** Install only when the application supports account termination. */
+export const subjectLifecycleLayer = Layer.mergeAll(
+  DisableSubject.handlerLayer(
+    Effect.fn("IdentityOperations.disableSubject")(function* (payload) {
+      const lifecycle = yield* SubjectLifecycle;
+
+      return yield* lifecycle.disable(payload);
+    }),
+  ),
+  DeleteSubject.handlerLayer(
+    Effect.fn("IdentityOperations.deleteSubject")(function* (payload) {
+      const lifecycle = yield* SubjectLifecycle;
+
+      return yield* lifecycle.delete(payload);
+    }),
+  ),
+);

package/src/index.ts

@@ -0,0 +1,23 @@
+export * as Auth from "./Auth.ts";
+export * as AuthContract from "./AuthContract.ts";
+export * as Client from "./Client.ts";
+export * as Email from "./Email.ts";
+export * as Hooks from "./Hooks.ts";
+export * as Identity from "./Identity.ts";
+export * as OAuth from "./OAuth.ts";
+export * as Operations from "./Operations.ts";
+export * as Passkey from "./Passkey.ts";
+export * as Password from "./Password.ts";
+export * as PhoneOtp from "./PhoneOtp.ts";
+export * as Proofs from "./Proofs.ts";
+export * as Schema from "./Schema.ts";
+export * as SessionContract from "./SessionContract.ts";
+export * as Sessions from "./Sessions.ts";
+export * as Totp from "./Totp.ts";
+export * as OperationHttp from "./OperationHttp.ts";
+export * as OperationHttpClient from "./OperationHttpClient.ts";
+export * as OperationHttpServer from "./OperationHttpServer.ts";
+export * as Atom from "./Atom.ts";
+
+export * as PasskeyContract from "./PasskeyContract.ts";
+export * as TotpContract from "./TotpContract.ts";

package/src/internal/AuthStoreDecisions.ts

@@ -0,0 +1,23 @@
+import { Context, type Effect } from "effect";
+
+import type { ConsumeDecision } from "../auth/ConsumeDecision";
+import type { EmailOtpRejectionReason } from "../AuthStore";
+import type { AuthStoreError } from "../Errors";
+import type { ConsumeChallenge, ConsumeRegistration, VerifiedEmail } from "../Schema";
+
+export type ChallengeConsumeDecision =
+  | { readonly _tag: "accepted"; readonly value: VerifiedEmail }
+  | { readonly _tag: "rejected"; readonly reason: typeof EmailOtpRejectionReason.Type };
+
+/** Translate rejected decisions only after the transaction commits. */
+export class AuthStoreDecisions extends Context.Service<
+  AuthStoreDecisions,
+  {
+    readonly consumeChallenge: (
+      input: ConsumeChallenge,
+    ) => Effect.Effect<ChallengeConsumeDecision, AuthStoreError>;
+    readonly consumeRegistration: (
+      input: ConsumeRegistration,
+    ) => Effect.Effect<ConsumeDecision<void>, AuthStoreError>;
+  }
+>()("effect-auth/AuthStoreDecisions") {}

package/src/internal/CurrentSession.ts

@@ -0,0 +1,8 @@
+import { Context } from "effect";
+
+import type { SessionClaims } from "../Schema";
+
+/** Authenticated session claims shared by HTTP and RPC transport middleware. */
+export class CurrentSession extends Context.Service<CurrentSession, SessionClaims>()(
+  "effect-auth/http/CurrentSession",
+) {}

package/src/internal/diagnostics.ts

@@ -0,0 +1,71 @@
+import { Cause, Context, Effect } from "effect";
+
+type FailureStage =
+  | "local"
+  | "rpc"
+  | "http"
+  | "success-projection"
+  | "error-projection"
+  | "private-output"
+  | "after-hook"
+  | "proof-delivery"
+  | "oauth-sign-in"
+  | "oauth-accounts"
+  | "oauth-exchange"
+  | "oauth-protocol"
+  | "oauth-identity"
+  | "oauth-connected"
+  | "oauth-registration"
+  | "session-sign-out"
+  | "password-screening"
+  | "password-hashing"
+  | "auth-persistence"
+  | "passkey-core"
+  | "passkey-protocol";
+
+/** Keep Effect's content-free frames, never failure values or arbitrary annotations. */
+export const reportAuthFailure = Effect.fn("AuthDiagnostics.reportFailure")(function* <E>(
+  stage: FailureStage,
+  cause: Cause.Cause<E>,
+): Effect.fn.Return<void> {
+  if (cause.reasons.length === 0 || Cause.hasInterruptsOnly(cause)) return;
+
+  const diagnostic = Cause.fromReasons(
+    cause.reasons.map((reason) => {
+      const error = new globalThis.Error(`Auth ${stage} failed`);
+
+      const safe = Cause.isDieReason(reason)
+        ? Cause.makeDieReason(error)
+        : Cause.isFailReason(reason)
+          ? Cause.makeFailReason(error)
+          : Cause.makeInterruptReason(reason.fiberId);
+
+      // Effect.fn / span names must themselves remain free of request content.
+      const frame = Context.getOrUndefined(Cause.reasonAnnotations(reason), Cause.StackTrace);
+
+      return frame === undefined ? safe : safe.annotate(Context.make(Cause.StackTrace, frame));
+    }),
+  );
+
+  yield* Effect.logError("Auth boundary failed", diagnostic);
+});
+
+/** Report only terminal unexpected persistence reasons, preserving the original Cause. */
+export const reportPersistenceFailure = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  isExpected: (error: E) => boolean,
+): Effect.Effect<A, E, R> =>
+  effect.pipe(
+    Effect.catchCause((cause): Effect.Effect<never, E> => {
+      const reasons = cause.reasons.filter(
+        (reason) =>
+          Cause.isDieReason(reason) || (Cause.isFailReason(reason) && !isExpected(reason.error)),
+      );
+
+      if (reasons.length === 0) return Effect.failCause(cause);
+
+      return reportAuthFailure("auth-persistence", Cause.fromReasons(reasons)).pipe(
+        Effect.andThen(Effect.failCause(cause)),
+      );
+    }),
+  );