@yielded/auth 0.1.0-beta.1

package/src/proofs/ProofPersistence.ts

@@ -0,0 +1,172 @@
+import { Context, type Effect } from "effect";
+
+import type { CommitJournal, PreparedCommit } from "../hooks/commit";
+import type { TokenDigest } from "../Schema";
+import type { ProofRequestConflict, ProofUnavailable } from "./errors";
+import type {
+  ProofAttemptDecision,
+  ProofBinding,
+  ProofCleanupResult,
+  ProofCompletionDecision,
+  ProofContinuationId,
+  ProofDeliveryId,
+  ProofDeliveryOutcome,
+  ProofId,
+  ProofPurpose,
+  ProofRequestId,
+  ProofRequestReceipt,
+  ProofVersion,
+} from "./models";
+import type { ProofPolicy } from "./policy";
+
+export interface ProofCompletionInput {
+  readonly moduleId: string;
+  readonly purpose: ProofPurpose;
+  readonly continuationId: ProofContinuationId;
+  readonly continuationDigest: TokenDigest;
+  readonly binding: ProofBinding;
+  readonly nowMillis: number;
+}
+
+export type PrepareProofCommit<Value, A> = (
+  value: Value,
+  journal: CommitJournal,
+) => PreparedCommit<A>;
+
+export interface ProofDigest {
+  readonly keyId: string;
+  readonly digest: TokenDigest;
+}
+
+export interface ProofRecord {
+  readonly moduleId: string;
+  readonly purpose: ProofPurpose;
+  readonly proofId: ProofId;
+  readonly requestId: ProofRequestId;
+  readonly fingerprint: TokenDigest;
+  readonly deliveryId: ProofDeliveryId;
+  readonly binding: ProofBinding;
+  readonly verifier: ProofDigest;
+  readonly issuedAtMillis: number;
+  readonly expiresAtMillis: number;
+  readonly version: ProofVersion;
+}
+
+export type ProofIssueDecision =
+  | { readonly _tag: "Issued"; readonly record: ProofRecord }
+  | { readonly _tag: "Existing" | "Suppressed"; readonly receipt: ProofRequestReceipt };
+
+export type ProofDeliveryClaim =
+  | { readonly _tag: "Claimed"; readonly claimVersion: ProofVersion }
+  | { readonly _tag: "Declined" };
+
+/**
+ * Semantic atomic commands, never generic CRUD. Every mutation owns the real
+ * transaction/batch and prepares its receipt BEFORE physical commit. Nested
+ * commands join the same owner. D1 preallocates final IDs/versions before batch.
+ * Use an authoritative fresh clock at each condition; caller timestamps are hints.
+ */
+export class ProofPersistence extends Context.Service<
+  ProofPersistence,
+  {
+    /**
+     * Atomically charge all identifier/subject/action issue windows (independent
+     * of flow/context/request IDs), enforce cooldown, insert a new active series
+     * generation, and supersede its predecessor. Preserve rolling failed-attempt
+     * history and send budgets across resends, consumption, cancellation and expiry.
+     * Matching request fingerprint returns Existing WITHOUT pairing its stored
+     * digest with this attempt's new secret. Mismatched reuse fails Conflict.
+     * eligible=false still charges existence-independent budgets and stores the
+     * request fingerprint, but creates no usable proof/delivery. Never disclose why.
+     * Check any captured security/credential/identifier revision against current authority.
+     */
+    readonly issue: <A>(
+      input: {
+        readonly record: ProofRecord;
+        readonly policy: ProofPolicy;
+        readonly eligible: boolean;
+        readonly supersedes?: ProofId;
+      },
+      prepare: PrepareProofCommit<ProofIssueDecision, A>,
+    ) => Effect.Effect<PreparedCommit<A>, ProofRequestConflict | ProofUnavailable>;
+    /**
+     * Charge action/identifier/subject attempt windows even for missing, mismatched,
+     * consumed or malformed candidates. Compare only the row's stored keyId.
+     * Enforce active generation, exact purpose/binding, current revisions, expiry,
+     * rolling failure budget and max failures atomically. One winner consumes proof
+     * and creates a digest-only restricted continuation whose expiry is clipped to
+     * min(proof.expiresAt, now+continuationLifetime); every rejection is a committed VALUE.
+     */
+    readonly attempt: <A>(
+      input: {
+        readonly moduleId: string;
+        readonly purpose: ProofPurpose;
+        readonly proofId: ProofId;
+        readonly binding: ProofBinding;
+        readonly candidate?: ProofDigest;
+        readonly continuationId: ProofContinuationId;
+        readonly continuationDigest: TokenDigest;
+        readonly nowMillis: number;
+        readonly policy: ProofPolicy;
+      },
+      prepare: PrepareProofCommit<ProofAttemptDecision, A>,
+    ) => Effect.Effect<PreparedCommit<A>, ProofUnavailable>;
+    /**
+     * Consume a continuation exactly once under matching module/purpose/binding,
+     * current revisions and expiry. Method adapters MUST couple this decision and
+     * protected credential/identifier/session writes in the same actual owner.
+     * The standalone operation chooses burn-on-downstream-failure; its result is
+     * never AuthenticationEvidence and cannot itself grant a session.
+     */
+    readonly complete: <A>(
+      input: ProofCompletionInput,
+      prepare: PrepareProofCommit<ProofCompletionDecision, A>,
+    ) => Effect.Effect<PreparedCommit<A>, ProofUnavailable>;
+    /**
+     * Persist a bounded send-attempt claim before network I/O. Check exact generation,
+     * active/unexpired proof and retry deadline. Concurrent/repeated calls have one
+     * claim winner. Expired claims become ambiguous; never reclaim an in-flight send
+     * as if it were definitely unsent. Only explicit idempotent-vendor retry may
+     * claim after ambiguity, with same deliveryId and within max attempt/lifetime.
+     */
+    readonly claimDelivery: <A>(
+      input: {
+        readonly moduleId: string;
+        readonly proofId: ProofId;
+        readonly version: ProofVersion;
+        readonly deliveryId: ProofDeliveryId;
+        readonly nowMillis: number;
+        readonly policy: ProofPolicy;
+        readonly allowAmbiguousRetry: boolean;
+      },
+      prepare: PrepareProofCommit<ProofDeliveryClaim, A>,
+    ) => Effect.Effect<PreparedCommit<A>, ProofUnavailable>;
+    /** Conditional on this claim/generation; an old failure cannot cancel a resend. Definite failure invalidates this proof, preserving every budget. */
+    readonly settleDelivery: <A>(
+      input: {
+        readonly moduleId: string;
+        readonly proofId: ProofId;
+        readonly version: ProofVersion;
+        readonly deliveryId: ProofDeliveryId;
+        readonly claimVersion: ProofVersion;
+        readonly outcome: ProofDeliveryOutcome;
+        readonly nowMillis: number;
+      },
+      prepare: PrepareProofCommit<void, A>,
+    ) => Effect.Effect<PreparedCommit<A>, ProofUnavailable>;
+    readonly cancel: <A>(
+      input: {
+        readonly moduleId: string;
+        readonly purpose: ProofPurpose;
+        readonly binding: ProofBinding;
+        readonly nowMillis: number;
+      },
+      prepare: PrepareProofCommit<void, A>,
+    ) => Effect.Effect<PreparedCommit<A>, ProofUnavailable>;
+    /** Bounded cleanup retains budgets/fingerprints/tombstones through their own horizons; erase verifiers and delivery material when no longer needed. */
+    readonly cleanup: <A>(
+      input: { readonly moduleId: string; readonly nowMillis: number; readonly limit: number },
+      prepare: PrepareProofCommit<ProofCleanupResult, A>,
+    ) => Effect.Effect<PreparedCommit<A>, ProofUnavailable>;
+  }
+>()("effect-auth/ProofPersistence") {}

package/src/proofs/SmsProofDelivery.ts

@@ -0,0 +1,19 @@
+import { Context, type Effect } from "effect";
+
+import {
+  type ProofDelivery,
+  type ProofDeliveryMessage,
+  type ProofVendorPolicy,
+  proofDeliveryLayer,
+} from "./delivery";
+import type { ProofDeliveryOutcome } from "./models";
+
+/** The consumer owns number/country eligibility, sender identity and vendor spend policy. */
+export class SmsProofDelivery extends Context.Service<SmsProofDelivery, ProofDelivery>()(
+  "effect-auth/SmsProofDelivery",
+) {
+  static readonly layer = <E, R>(
+    vendor: ProofVendorPolicy,
+    send: (message: ProofDeliveryMessage) => Effect.Effect<ProofDeliveryOutcome, E, R>,
+  ) => proofDeliveryLayer(this, vendor, send);
+}

package/src/proofs/abuse.ts

@@ -0,0 +1,23 @@
+import { LoginIdentifier } from "../identity/models";
+import type { SubjectId } from "../Schema";
+import type { ProofBinding, ProofPurpose } from "./models";
+
+/** Structured composite keys. Every dimension is independent of flow, context, request, and proof IDs. */
+export interface ProofAbuseScope {
+  readonly moduleId: string;
+  readonly purpose: ProofPurpose;
+  readonly identifier: LoginIdentifier;
+  readonly subjectId?: SubjectId;
+}
+
+export const proofAbuseScope = (
+  moduleId: string,
+  purpose: ProofPurpose,
+  binding: ProofBinding,
+): ProofAbuseScope =>
+  Object.freeze({
+    moduleId,
+    purpose,
+    identifier: Object.freeze(LoginIdentifier.make(binding.identifier)),
+    ...(binding._tag === "Identifier" ? {} : { subjectId: binding.revision.subjectId }),
+  });

package/src/proofs/completion.ts

@@ -0,0 +1,23 @@
+import type { CommitJournal, PreparedCommit } from "../hooks/commit";
+import type { ProofCompletionDecision } from "./models";
+import type { ProofCompletionInput } from "./ProofPersistence";
+
+/** Server-internal plan for method-specific atomic commands. Never serialize this
+ * digest-bearing object. The driver consumes input and performs its protected
+ * mutation under the SAME decision/transaction, then calls prepare before commit.
+ * Report completed only if both continuation CAS and protected write apply; a
+ * zero-row/stale protected write must reject or roll back the same authority.
+ * D1 compiles conditional statements; this API does not run arbitrary callbacks
+ * inside a batch. The callback only projects a precomputed decision, synchronously.
+ * Keep the original action/flow binding stable. Material chosen later needs
+ * separate trusted action authorization, not a rewrite of this proof binding.
+ * Public context must not contain plaintext secrets or guessable secret hashes.
+ */
+export interface ProofCompletionPlan {
+  readonly input: ProofCompletionInput;
+  readonly prepare: <A>(
+    decision: ProofCompletionDecision,
+    journal: CommitJournal,
+    project: (decision: ProofCompletionDecision) => A,
+  ) => PreparedCommit<A>;
+}

package/src/proofs/crypto.ts

@@ -0,0 +1,326 @@
+import { Crypto, Effect, Encoding, Redacted, Result, Schema } from "effect";
+
+import { TokenDigest } from "../Schema";
+import { SubtleCrypto } from "../WebCrypto";
+import { ProofConfigurationError, ProofUnavailable } from "./errors";
+import { ProofBinding, type ProofId, type ProofPurpose } from "./models";
+import type { ProofDigest } from "./ProofPersistence";
+
+export const ProofSecretPolicy = Schema.Union([
+  Schema.TaggedStruct("Token", {}),
+  Schema.TaggedStruct("NumericCode", {
+    digits: Schema.Int.check(Schema.isBetween({ minimum: 6, maximum: 10 })),
+  }),
+]);
+
+export type ProofSecretPolicy = typeof ProofSecretPolicy.Type;
+
+export interface ProofKeyring {
+  readonly activeKeyId: string;
+  readonly keys: ReadonlyArray<{
+    readonly id: string;
+    readonly material: Redacted.Redacted<string>;
+  }>;
+}
+
+const KeyId = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_-]{1,64}$/));
+
+const Keyring = Schema.Struct({
+  activeKeyId: KeyId,
+  keys: Schema.Array(Schema.Struct({ id: KeyId, material: Schema.Redacted(Schema.String) })).check(
+    Schema.isMinLength(1),
+    Schema.isMaxLength(8),
+  ),
+});
+
+const OpaqueSecret = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_-]{43}$/));
+const encoder = new TextEncoder();
+
+/** Versioned fixed tuples: no dynamic object key ordering or delimiter ambiguity. */
+const BindingTuple = Schema.Tuple([
+  Schema.String,
+  Schema.String,
+  Schema.String,
+  Schema.String,
+  Schema.String,
+  Schema.Array(Schema.Tuple([Schema.String, Schema.String])),
+  Schema.String,
+  Schema.String,
+]);
+
+const DigestInput = Schema.fromJsonString(
+  Schema.Tuple([
+    Schema.Literal("effect-auth/proof/v1"),
+    Schema.String,
+    Schema.String,
+    Schema.String,
+    BindingTuple,
+    Schema.String,
+    Schema.String,
+  ]),
+);
+
+const FingerprintInput = Schema.fromJsonString(
+  Schema.Tuple([
+    Schema.Literal("effect-auth/proof-request/v1"),
+    Schema.String,
+    Schema.String,
+    BindingTuple,
+    Schema.String,
+    Schema.String,
+    Schema.String,
+    Schema.String,
+    Schema.String,
+  ]),
+);
+
+const bindingTuple = (binding: ProofBinding): typeof BindingTuple.Type => {
+  const revision = binding._tag === "Identifier" ? undefined : binding.revision;
+
+  return [
+    binding._tag,
+    binding.identifier.namespace,
+    binding.identifier.value,
+    revision?.subjectId ?? "",
+    revision?.securityRevision ?? "",
+    [...(revision?.credentials ?? [])]
+      .map((item) => [item.credentialId, item.revision] as const)
+      .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)),
+    binding.flowId,
+    binding.contextDigest,
+  ];
+};
+
+export const validateProofBinding = Effect.fn("validateProofBinding")(function* (
+  input: ProofBinding,
+) {
+  const binding = yield* Schema.decodeEffect(ProofBinding)(input).pipe(
+    Effect.mapError(() => ProofUnavailable.make({})),
+  );
+
+  if (binding._tag !== "Identifier") {
+    const ids = new Set<string>();
+
+    for (const credential of binding.revision.credentials) {
+      if (ids.has(credential.credentialId)) return yield* ProofUnavailable.make({});
+      ids.add(credential.credentialId);
+    }
+  }
+  const identifier = Object.freeze(binding.identifier);
+
+  return binding._tag === "Identifier"
+    ? Object.freeze({ ...binding, identifier })
+    : Object.freeze({
+        ...binding,
+        identifier,
+        revision: Object.freeze({
+          ...binding.revision,
+          credentials: Object.freeze(
+            [...binding.revision.credentials]
+              .sort((a, b) =>
+                a.credentialId < b.credentialId ? -1 : a.credentialId > b.credentialId ? 1 : 0,
+              )
+              .map((value) => Object.freeze({ ...value })),
+          ),
+        }),
+      });
+});
+
+export const makeProofCrypto = Effect.fn("makeProofCrypto")(function* (
+  moduleId: string,
+  purpose: ProofPurpose,
+  input: ProofSecretPolicy,
+  configuredKeys?: ProofKeyring,
+) {
+  const policy = yield* Schema.decodeEffect(ProofSecretPolicy)(input).pipe(
+    Effect.mapError(() => ProofConfigurationError.make({ reason: "policy" })),
+  );
+
+  const crypto = yield* Crypto.Crypto;
+  const subtle = yield* SubtleCrypto;
+  const keys = new Map<string, CryptoKey>();
+  let activeKeyId = "token";
+
+  if (policy._tag === "NumericCode") {
+    if (configuredKeys === undefined)
+      return yield* ProofConfigurationError.make({ reason: "keyring" });
+
+    const keyring = yield* Schema.decodeEffect(Keyring)(configuredKeys).pipe(
+      Effect.mapError(() => ProofConfigurationError.make({ reason: "keyring" })),
+    );
+
+    for (const entry of keyring.keys) {
+      const material = Result.getOrUndefined(
+        Encoding.decodeBase64Url(Redacted.value(entry.material)),
+      );
+
+      if (
+        entry.id === "token" ||
+        keys.has(entry.id) ||
+        material === undefined ||
+        material.length < 32
+      )
+        return yield* ProofConfigurationError.make({ reason: "keyring" });
+
+      const key = yield* Effect.tryPromise({
+        try: () =>
+          subtle.importKey(
+            "raw",
+            material as BufferSource,
+            { name: "HMAC", hash: "SHA-256" },
+            false,
+            ["sign"],
+          ),
+        catch: () => ProofConfigurationError.make({ reason: "keyring" }),
+      });
+
+      keys.set(entry.id, key);
+    }
+    activeKeyId = keyring.activeKeyId;
+    if (!keys.has(activeKeyId)) return yield* ProofConfigurationError.make({ reason: "keyring" });
+  }
+
+  const generateOpaque = Effect.fn("ProofCrypto.generateOpaque")(function* () {
+    return Redacted.make(
+      Encoding.encodeBase64Url(
+        yield* crypto.randomBytes(32).pipe(Effect.mapError(() => ProofUnavailable.make({}))),
+      ),
+    );
+  });
+
+  const generate = Effect.fn("ProofCrypto.generate")(function* () {
+    if (policy._tag === "Token") return yield* generateOpaque();
+    let code = "";
+
+    // Rejection sampling preserves leading zeroes and avoids modulo bias.
+    for (let batch = 0; batch < 8 && code.length < policy.digits; batch++)
+      for (const byte of yield* crypto
+        .randomBytes(policy.digits * 2)
+        .pipe(Effect.mapError(() => ProofUnavailable.make({}))))
+        if (byte < 250 && code.length < policy.digits) code += String(byte % 10);
+    if (code.length !== policy.digits) return yield* ProofUnavailable.make({});
+
+    return Redacted.make(code);
+  });
+
+  const digest = Effect.fn("ProofCrypto.digest")(function* (
+    proofId: ProofId,
+    binding: ProofBinding,
+    secret: Redacted.Redacted<string>,
+    keyId: string,
+  ): Effect.fn.Return<ProofDigest | undefined, ProofUnavailable> {
+    binding = yield* validateProofBinding(binding);
+    const value = Redacted.value(secret);
+
+    const secretSchema =
+      policy._tag === "Token"
+        ? OpaqueSecret
+        : Schema.String.check(Schema.isPattern(new RegExp(`^[0-9]{${policy.digits}}$`)));
+
+    if (
+      !Schema.is(secretSchema)(value) ||
+      (policy._tag === "Token" ? keyId !== "token" : !keys.has(keyId))
+    )
+      return undefined;
+
+    const message = yield* Schema.encodeEffect(DigestInput)([
+      "effect-auth/proof/v1",
+      moduleId,
+      purpose,
+      proofId,
+      bindingTuple(binding),
+      keyId,
+      value,
+    ]).pipe(Effect.mapError(() => ProofUnavailable.make({})));
+
+    if (encoder.encode(message).byteLength > 16384) return yield* ProofUnavailable.make({});
+
+    const bytes =
+      policy._tag === "Token"
+        ? yield* crypto
+            .digest("SHA-256", encoder.encode(message))
+            .pipe(Effect.mapError(() => ProofUnavailable.make({})))
+        : new Uint8Array(
+            yield* Effect.tryPromise({
+              try: () => subtle.sign("HMAC", keys.get(keyId)!, encoder.encode(message)),
+              catch: () => ProofUnavailable.make({}),
+            }),
+          );
+
+    return { keyId, digest: TokenDigest.make(Encoding.encodeBase64Url(bytes)) };
+  });
+
+  const continuationDigest = Effect.fn("ProofCrypto.continuationDigest")(function* (
+    id: string,
+    binding: ProofBinding,
+    secret: Redacted.Redacted<string>,
+  ) {
+    binding = yield* validateProofBinding(binding);
+    if (!Schema.is(OpaqueSecret)(Redacted.value(secret))) return undefined;
+
+    const message = yield* Schema.encodeEffect(DigestInput)([
+      "effect-auth/proof/v1",
+      moduleId,
+      purpose,
+      id,
+      bindingTuple(binding),
+      "continuation",
+      Redacted.value(secret),
+    ]).pipe(Effect.mapError(() => ProofUnavailable.make({})));
+
+    if (encoder.encode(message).byteLength > 16384) return yield* ProofUnavailable.make({});
+
+    return TokenDigest.make(
+      Encoding.encodeBase64Url(
+        yield* crypto
+          .digest("SHA-256", encoder.encode(message))
+          .pipe(Effect.mapError(() => ProofUnavailable.make({}))),
+      ),
+    );
+  });
+
+  const fingerprint = Effect.fn("ProofCrypto.fingerprint")(function* (
+    binding: ProofBinding,
+    delivery: {
+      readonly channel: string;
+      readonly vendor: string;
+      readonly template: string;
+      readonly locale: string;
+    },
+    supersedes?: ProofId,
+  ) {
+    binding = yield* validateProofBinding(binding);
+
+    const message = yield* Schema.encodeEffect(FingerprintInput)([
+      "effect-auth/proof-request/v1",
+      moduleId,
+      purpose,
+      bindingTuple(binding),
+      delivery.channel,
+      delivery.vendor,
+      delivery.template,
+      delivery.locale,
+      supersedes ?? "",
+    ]).pipe(Effect.mapError(() => ProofUnavailable.make({})));
+
+    if (encoder.encode(message).byteLength > 16384) return yield* ProofUnavailable.make({});
+
+    return TokenDigest.make(
+      Encoding.encodeBase64Url(
+        yield* crypto
+          .digest("SHA-256", encoder.encode(message))
+          .pipe(Effect.mapError(() => ProofUnavailable.make({}))),
+      ),
+    );
+  });
+
+  return Object.freeze({
+    activeKeyId,
+    format: policy._tag === "Token" ? ("token" as const) : ("numeric-code" as const),
+    generate,
+    generateOpaque,
+    digest,
+    continuationDigest,
+    fingerprint,
+  });
+});

package/src/proofs/definition.ts

@@ -0,0 +1,39 @@
+import type { Schema } from "effect";
+
+import type { ProofBinding } from "./models";
+import { makeProofModule } from "./module";
+
+type Options<Binding extends Schema.Codec<ProofBinding, unknown, unknown, unknown>> = Parameters<
+  typeof makeProofModule<string, Binding>
+>[1];
+
+type NamespaceOf<Id> = Id extends string ? Id : "effect-auth/proofs";
+
+const define = <
+  Binding extends Schema.Codec<ProofBinding, unknown, unknown, unknown>,
+  const Id extends string | undefined,
+>(
+  namespace: Id,
+  options: Options<Binding>,
+) =>
+  // The required namespace argument preserves whether a default can be selected.
+  makeProofModule((namespace ?? "effect-auth/proofs") as NamespaceOf<Id>, options);
+
+export function make<
+  Binding extends Schema.Codec<ProofBinding, unknown, unknown, unknown>,
+  const Id extends string,
+>(options: Options<Binding> & { readonly namespace: Id }): ReturnType<typeof define<Binding, Id>>;
+
+export function make<
+  Binding extends Schema.Codec<ProofBinding, unknown, unknown, unknown>,
+  const Id extends string | undefined = undefined,
+>(
+  options: Options<Binding> & { readonly namespace?: Id },
+): ReturnType<typeof define<Binding, Id | undefined>>;
+
+export function make<
+  Binding extends Schema.Codec<ProofBinding, unknown, unknown, unknown>,
+  const Id extends string | undefined,
+>(options: Options<Binding> & { readonly namespace?: Id }) {
+  return define(options.namespace, options);
+}

package/src/proofs/delivery.ts

@@ -0,0 +1,73 @@
+import { Effect, Layer, type Context, type Redacted, Schema } from "effect";
+
+import type { LoginIdentifier } from "../identity/models";
+import { reportAuthFailure } from "../internal/diagnostics";
+import { ProofConfigurationError } from "./errors";
+import {
+  ProofDeliveryOutcome,
+  type ProofDeliveryId,
+  type ProofPurpose,
+  type ProofReference,
+} from "./models";
+
+export interface ProofDeliveryMessage {
+  readonly deliveryId: ProofDeliveryId;
+  readonly purpose: ProofPurpose;
+  readonly reference: ProofReference;
+  readonly recipient: LoginIdentifier;
+  readonly secret: Redacted.Redacted<string>;
+  readonly format: "token" | "numeric-code";
+  readonly expiresAtMillis: number;
+  readonly template: string;
+  readonly locale: string;
+}
+
+export const ProofVendorPolicy = Schema.Struct({
+  vendorId: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(128)),
+  /** A consumer asserts the vendor deduplicates identical delivery IDs for this horizon. */
+  idempotencyMillis: Schema.Natural,
+});
+
+export type ProofVendorPolicy = typeof ProofVendorPolicy.Type;
+
+export interface ProofDelivery {
+  readonly vendor: ProofVendorPolicy;
+  /** Acceptance by vendor is not delivery to the recipient. No diagnostic/body escapes this boundary. */
+  readonly send: (message: ProofDeliveryMessage) => Effect.Effect<ProofDeliveryOutcome>;
+}
+
+export const proofDeliveryLayer = <Id, E, R>(
+  service: Context.Key<Id, ProofDelivery>,
+  vendor: ProofVendorPolicy,
+  send: (message: ProofDeliveryMessage) => Effect.Effect<ProofDeliveryOutcome, E, R>,
+) => {
+  const configuration = { ...vendor };
+  const callback = send;
+
+  return Layer.effect(
+    service,
+    Effect.gen(function* () {
+      const checked = Object.freeze(
+        yield* Schema.decodeEffect(ProofVendorPolicy)(configuration).pipe(
+          Effect.mapError(() => ProofConfigurationError.make({ reason: "delivery" })),
+        ),
+      );
+
+      const services = yield* Effect.context<R>();
+
+      return {
+        vendor: checked,
+        send: (message: ProofDeliveryMessage) =>
+          Effect.suspend(() => callback(message)).pipe(
+            Effect.provide(services),
+            Effect.flatMap(Schema.decodeEffect(ProofDeliveryOutcome)),
+            Effect.catchCause((cause) =>
+              reportAuthFailure("proof-delivery", cause).pipe(
+                Effect.as({ _tag: "Ambiguous" as const }),
+              ),
+            ),
+          ),
+      };
+    }),
+  );
+};