@yielded/auth 0.1.0-beta.1

package/src/hooks/commit.ts

@@ -0,0 +1,271 @@
+import { Cause, Context, Effect, Option, Schema } from "effect";
+
+import { LifecycleHooks } from "./LifecycleHooks";
+import {
+  HookConfigurationError,
+  type HookDelivery,
+  type LifecycleEvent,
+  type LifecycleEventId,
+  lifecycleEvent,
+} from "./models";
+import { type AtomicContribution, type CommitMode, validateContributions } from "./transactions";
+
+export class CommitPending extends Schema.TaggedError<CommitPending>()("CommitPending", {}) {}
+export class CommitDiscarded extends Schema.TaggedError<CommitDiscarded>()("CommitDiscarded", {}) {}
+
+/** No value is exposed until the outermost transaction authority has committed. */
+export interface PreparedCommit<A> {
+  readonly _tag: "PreparedCommit";
+  readonly read: Effect.Effect<A, CommitPending | CommitDiscarded>;
+}
+
+interface CommitParticipant {
+  readonly commit: () => void;
+  readonly discard: () => void;
+}
+
+export interface CommitJournal {
+  readonly prepare: <A>(value: A) => PreparedCommit<A>;
+  /** Stage only work belonging to this transaction/savepoint, before its commit returns. */
+  readonly stage: (event: LifecycleEvent) => void;
+  /** Call only after staging this event's outbox write in the same transaction/batch. */
+  readonly defer: (event: LifecycleEvent) => void;
+}
+
+/** Current journal for internal transaction operations. Public commit-owner
+ * continuations still receive the journal explicitly at the native boundary. */
+export class CurrentCommitJournal extends Context.Service<CurrentCommitJournal, CommitJournal>()(
+  "effect-auth/hooks/CurrentCommitJournal",
+) {}
+
+interface StagedEvent {
+  readonly event: LifecycleEvent;
+  readonly deferred: boolean;
+}
+
+class CurrentCommit extends Context.Service<
+  CurrentCommit,
+  {
+    readonly reservations: Set<string>;
+    readonly assertOpen: () => void;
+    readonly promote: (
+      events: ReadonlyArray<StagedEvent>,
+      participants: ReadonlyArray<CommitParticipant>,
+      reservations: ReadonlySet<string>,
+    ) => void;
+  }
+>()("effect-auth/hooks/CurrentCommit") {}
+
+/** Public operations may reject unsupported ambient execution before any mutation. */
+export const hasCommitScope = Effect.serviceOption(CurrentCommit).pipe(Effect.map(Option.isSome));
+
+export type CommitResult<A> =
+  | { readonly _tag: "PendingCommit"; readonly value: A }
+  | {
+      readonly _tag: "Committed";
+      readonly value: A;
+      readonly delivery: ReadonlyArray<HookDelivery>;
+      readonly deferred: ReadonlyArray<LifecycleEventId>;
+    };
+
+/**
+ * `owner` must resolve only after its real transaction or batch commits. Nested
+ * calls inherit the outer journal; their events are discarded on failure and
+ * cannot dispatch until the outermost owner succeeds. Wrap a caught savepoint
+ * rollback in its own coordinateCommit call so its events are discarded too.
+ * Direct delivery is best effort: a process crash loses staged memory and no
+ * retry is automatic. Once the owner returns, interruption is masked during
+ * dispatch; that makes reporting coherent, not durable. An outbox owner stages
+ * its writes before calling journal.defer and owns worker retries/deduplication.
+ */
+export const coordinateCommit = <A, E, R>(
+  owner: (journal: CommitJournal) => Effect.Effect<A, E, R>,
+  options: {
+    readonly mode: CommitMode;
+    readonly contributions?: ReadonlyArray<AtomicContribution>;
+  },
+): Effect.Effect<
+  CommitResult<A>,
+  E | HookConfigurationError,
+  Exclude<R, CurrentCommitJournal> | LifecycleHooks
+> =>
+  Effect.uninterruptibleMask((restore) =>
+    Effect.gen(function* () {
+      yield* Effect.try({
+        try: () => validateContributions(options.mode, options.contributions ?? []),
+        catch: (error) =>
+          Schema.is(HookConfigurationError)(error)
+            ? error
+            : HookConfigurationError.make({
+                reason: "incompatible-transaction",
+                contribution: "transaction",
+              }),
+      });
+      const parent = yield* Effect.serviceOption(CurrentCommit);
+      const hooks = yield* LifecycleHooks;
+      const events: StagedEvent[] = [];
+      const participants: CommitParticipant[] = [];
+      const reservations = Option.isSome(parent) ? parent.value.reservations : new Set<string>();
+      const ownedReservations = new Set<string>();
+
+      const discard = Effect.sync(() => {
+        for (const participant of participants) participant.discard();
+        for (const id of ownedReservations) reservations.delete(id);
+        ownedReservations.clear();
+      });
+
+      let open = true;
+
+      const assertOpen = (): void => {
+        if (!open)
+          throw HookConfigurationError.make({
+            reason: "closed-journal",
+            contribution: "transaction",
+          });
+        if (Option.isSome(parent)) parent.value.assertOpen();
+      };
+
+      const append = (
+        incoming: ReadonlyArray<StagedEvent>,
+        incomingParticipants: ReadonlyArray<CommitParticipant> = [],
+      ): void => {
+        assertOpen();
+        const next = new Set(reservations);
+
+        for (const { event } of incoming) {
+          if (next.has(event.id))
+            throw HookConfigurationError.make({
+              reason: "duplicate-event",
+              contribution: event.id,
+            });
+          next.add(event.id);
+        }
+        // Reserve while the native owner can still roll back. Successful child
+        // owners transfer these reservations without another duplicate check.
+        for (const item of incoming) {
+          reservations.add(item.event.id);
+          ownedReservations.add(item.event.id);
+          events.push(item);
+        }
+        participants.push(...incomingParticipants);
+      };
+
+      const promote = (
+        incoming: ReadonlyArray<StagedEvent>,
+        incomingParticipants: ReadonlyArray<CommitParticipant>,
+        incomingReservations: ReadonlySet<string>,
+      ): void => {
+        assertOpen();
+        events.push(...incoming);
+        participants.push(...incomingParticipants);
+        for (const id of incomingReservations) ownedReservations.add(id);
+      };
+
+      const journal: CommitJournal = {
+        prepare: <A>(input: A): PreparedCommit<A> => {
+          let status: "pending" | "committed" | "discarded" = "pending";
+          let value: Option.Option<A> = Option.some(input);
+
+          append(
+            [],
+            [
+              {
+                commit: () => {
+                  status = "committed";
+                },
+                discard: () => {
+                  status = "discarded";
+                  value = Option.none();
+                },
+              },
+            ],
+          );
+
+          return Object.freeze({
+            _tag: "PreparedCommit",
+            read: Effect.suspend((): Effect.Effect<A, CommitPending | CommitDiscarded> =>
+              status === "committed" && Option.isSome(value)
+                ? Effect.succeed(value.value)
+                : status === "discarded"
+                  ? Effect.fail(CommitDiscarded.make({}))
+                  : Effect.fail(CommitPending.make({})),
+            ),
+          });
+        },
+        stage: (input) => append([{ event: lifecycleEvent(input), deferred: false }]),
+        defer: (input) => append([{ event: lifecycleEvent(input), deferred: true }]),
+      };
+
+      const value = yield* restore(Effect.suspend(() => owner(journal))).pipe(
+        Effect.provideService(CurrentCommitJournal, journal),
+        Effect.provideService(CurrentCommit, { reservations, assertOpen, promote }),
+        // Synchronous journal methods can throw inside an Effect callback. The
+        // owner's failed transaction has rolled back before we normalize them.
+        // Mixed causes stay intact so typed recovery cannot swallow a defect or interruption.
+        Effect.catchCause((cause) =>
+          Effect.failCause(
+            cause.reasons.every(
+              (reason) =>
+                Cause.isDieReason(reason) && Schema.is(HookConfigurationError)(reason.defect),
+            )
+              ? Cause.fromReasons<E | HookConfigurationError>(
+                  cause.reasons.map((reason) =>
+                    Cause.isDieReason(reason) && Schema.is(HookConfigurationError)(reason.defect)
+                      ? Cause.makeFailReason(reason.defect).annotate(
+                          Cause.reasonAnnotations(reason),
+                        )
+                      : reason,
+                  ),
+                )
+              : cause,
+          ),
+        ),
+        Effect.onError(() => discard),
+        Effect.ensuring(
+          Effect.sync(() => {
+            open = false;
+          }),
+        ),
+      );
+
+      if (Option.isSome(parent)) {
+        yield* Effect.try({
+          try: () => parent.value.promote(events, participants, ownedReservations),
+          catch: (error) =>
+            Schema.is(HookConfigurationError)(error)
+              ? error
+              : HookConfigurationError.make({
+                  reason: "closed-journal",
+                  contribution: "transaction",
+                }),
+        }).pipe(Effect.onError(() => discard));
+
+        return { _tag: "PendingCommit", value } as const;
+      }
+      for (const participant of participants) participant.commit();
+      const delivery: HookDelivery[] = [];
+      const deferred: LifecycleEventId[] = [];
+
+      for (const { event, deferred: isDeferred } of events) {
+        if (isDeferred) deferred.push(event.id);
+        else delivery.push(...(yield* hooks.after(event)));
+      }
+
+      return { _tag: "Committed", value, delivery, deferred } as const;
+    }),
+  );
+
+/**
+ * An outbox implementation stages this immutable event in the same authority's
+ * transaction/batch. A delivery worker later calls LifecycleHooks.after(event),
+ * retaining the same ID on every attempt and deduplicating each contribution.
+ * Delivery is at least once when the consumer provides persistence and retries;
+ * this interface alone supplies no persistence or exactly-once guarantee.
+ */
+export interface EventOutbox<E = never, R = never> {
+  readonly stage: (event: LifecycleEvent) => Effect.Effect<void, E, R>;
+}
+
+export interface BatchEventOutbox<Statement> {
+  readonly statements: (event: LifecycleEvent) => ReadonlyArray<Statement>;
+}

package/src/hooks/models.ts

@@ -0,0 +1,111 @@
+import { Schema } from "effect";
+
+import { LoginIdentifier } from "../identity/models";
+import { SubjectId } from "../Schema";
+
+export const LifecycleAction = Schema.Literals([
+  "registration",
+  "sign-in",
+  "session-creation",
+  "credential-change",
+  "factor-change",
+  "identifier-change",
+  "linking",
+  "sign-out",
+  "proof-request",
+  "proof-verification",
+  "proof-completion",
+]);
+
+export type LifecycleAction = typeof LifecycleAction.Type;
+
+/** Deliberately excludes credentials, proofs, tokens, claims, and verification authority. */
+export const LifecycleSnapshot = Schema.Struct({
+  action: LifecycleAction,
+  operation: Schema.NonEmptyString,
+  subjectId: Schema.optionalKey(SubjectId),
+  method: Schema.optionalKey(Schema.NonEmptyString),
+  identifiers: Schema.Array(LoginIdentifier),
+});
+
+export type LifecycleSnapshot = typeof LifecycleSnapshot.Type;
+
+export const LifecycleEventId = Schema.NonEmptyString.pipe(
+  Schema.brand("effect-auth/LifecycleEventId"),
+);
+
+export type LifecycleEventId = typeof LifecycleEventId.Type;
+
+/** The owner supplies a stable, nonsecret identifier; delivery retries reuse this exact event. */
+export const LifecycleEvent = Schema.Struct({
+  id: LifecycleEventId,
+  occurredAtMillis: Schema.Int.check(
+    Schema.isBetween({ minimum: -8640000000000000, maximum: 8640000000000000 }),
+  ),
+  snapshot: LifecycleSnapshot,
+});
+
+export type LifecycleEvent = typeof LifecycleEvent.Type;
+
+export class HookDenied extends Schema.TaggedError<HookDenied>()("HookDenied", {
+  reason: Schema.Literals(["policy", "unavailable"]),
+}) {}
+
+export class HookDeliveryFailed extends Schema.TaggedError<HookDeliveryFailed>()(
+  "HookDeliveryFailed",
+  {},
+) {}
+
+export class HookConfigurationError extends Schema.TaggedError<HookConfigurationError>()(
+  "HookConfigurationError",
+  {
+    reason: Schema.Literals([
+      "duplicate-contribution",
+      "duplicate-event",
+      "duplicate-route",
+      "incompatible-transaction",
+      "closed-journal",
+      "invalid-snapshot",
+    ]),
+    contribution: Schema.String,
+  },
+) {}
+
+export interface HookDelivery {
+  readonly eventId: LifecycleEventId;
+  readonly contribution: string;
+  readonly status: "delivered" | "failed";
+}
+
+const snapshotCodec = Schema.toCodecIso(LifecycleSnapshot);
+const encodeSnapshot = Schema.encodeSync(snapshotCodec);
+const decodeSnapshot = Schema.decodeSync(snapshotCodec);
+const eventCodec = Schema.toCodecIso(LifecycleEvent);
+const encodeEvent = Schema.encodeSync(eventCodec);
+const decodeEvent = Schema.decodeSync(eventCodec);
+
+/** Projection also strips undeclared own properties of identifier Schema.Class instances. */
+export const lifecycleSnapshot = (input: LifecycleSnapshot): LifecycleSnapshot => {
+  try {
+    const snapshot = decodeSnapshot(encodeSnapshot(input));
+
+    return Object.freeze({
+      ...snapshot,
+      identifiers: Object.freeze(
+        snapshot.identifiers.map((identifier) => Object.freeze(identifier)),
+      ),
+    });
+  } catch {
+    throw HookConfigurationError.make({ reason: "invalid-snapshot", contribution: "snapshot" });
+  }
+};
+
+export const lifecycleEvent = (input: LifecycleEvent): LifecycleEvent => {
+  try {
+    const event = decodeEvent(encodeEvent(input));
+
+    return Object.freeze({ ...event, snapshot: lifecycleSnapshot(event.snapshot) });
+  } catch {
+    throw HookConfigurationError.make({ reason: "invalid-snapshot", contribution: "event" });
+  }
+};

package/src/hooks/plugins.ts

@@ -0,0 +1,87 @@
+import type { RpcGroup } from "effect/unstable/rpc";
+
+import { type AnyOperation, operationGroup } from "../operations/operation";
+import { type AnyHookContribution, composeHooks } from "./LifecycleHooks";
+import { HookConfigurationError } from "./models";
+
+/** Host-owned route implementation; metadata only reserves the method/path pair. */
+export interface RouteContribution {
+  readonly id: string;
+  readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
+  readonly path: string;
+}
+
+export interface PluginContributions {
+  readonly id: string;
+  readonly operations: ReadonlyArray<AnyOperation>;
+  readonly hooks: ReadonlyArray<AnyHookContribution>;
+  readonly routes: ReadonlyArray<RouteContribution>;
+}
+
+/** Optional aggregation metadata alongside ordinary exported implementation Layers. */
+export const pluginContributions = <const Contributions extends PluginContributions>(
+  contributions: Contributions,
+) =>
+  Object.freeze({
+    id: contributions.id,
+    operations: Object.freeze([...contributions.operations]) as Contributions["operations"],
+    hooks: Object.freeze([...contributions.hooks]) as Contributions["hooks"],
+    routes: Object.freeze(
+      contributions.routes.map((route) => Object.freeze({ ...route })),
+    ) as Contributions["routes"],
+  });
+
+export const composePlugins = <const Plugins extends ReadonlyArray<PluginContributions>>(
+  ...plugins: Plugins
+) => {
+  const snapshots = plugins.map((plugin) => ({
+    id: plugin.id,
+    operations: [...plugin.operations],
+    hooks: plugin.hooks.map(({ id, resolve }) => Object.freeze({ id, resolve })),
+    routes: plugin.routes.map((route) => Object.freeze({ ...route })),
+  }));
+
+  const ids = new Set<string>();
+  const hookIds = new Set<string>();
+  const routeIds = new Set<string>();
+  const routeKeys = new Set<string>();
+
+  for (const plugin of snapshots) {
+    if (ids.has(plugin.id))
+      throw HookConfigurationError.make({
+        reason: "duplicate-contribution",
+        contribution: plugin.id,
+      });
+    ids.add(plugin.id);
+    for (const hook of plugin.hooks) {
+      if (hookIds.has(hook.id))
+        throw HookConfigurationError.make({
+          reason: "duplicate-contribution",
+          contribution: hook.id,
+        });
+      hookIds.add(hook.id);
+    }
+    for (const route of plugin.routes) {
+      const key = `${route.method} ${route.path}`;
+
+      if (routeIds.has(route.id) || routeKeys.has(key))
+        throw HookConfigurationError.make({ reason: "duplicate-route", contribution: route.id });
+      routeIds.add(route.id);
+      routeKeys.add(key);
+    }
+  }
+  const operations = snapshots.flatMap((plugin) => plugin.operations);
+
+  const hooks = snapshots.flatMap((plugin) => plugin.hooks) as Array<
+    Plugins[number]["hooks"][number]
+  >;
+
+  return Object.freeze({
+    // Array flattening erases tuple membership; every RPC comes from these validated contributions.
+    operations: operationGroup(...operations) as RpcGroup.RpcGroup<
+      Plugins[number]["operations"][number]["rpc"]
+    >,
+    hooks: composeHooks<Plugins[number]["hooks"][number]["id"]>(...hooks),
+    routes: Object.freeze(snapshots.flatMap((plugin) => plugin.routes)),
+  });
+};

package/src/hooks/transactions.ts

@@ -0,0 +1,51 @@
+import type { Effect } from "effect";
+
+import { HookConfigurationError, type LifecycleSnapshot } from "./models";
+
+export type CommitMode = "interactive" | "synchronous" | "batch";
+
+export interface AtomicContribution {
+  readonly id: string;
+  readonly mode: CommitMode;
+  /** Static validation, before the transaction owner executes any writes. */
+  readonly validate?: () => void;
+}
+
+export const validateContributions = (
+  mode: CommitMode,
+  contributions: ReadonlyArray<AtomicContribution>,
+): void => {
+  const ids = new Set<string>();
+
+  for (const contribution of contributions) {
+    if (ids.has(contribution.id))
+      throw HookConfigurationError.make({
+        reason: "duplicate-contribution",
+        contribution: contribution.id,
+      });
+    ids.add(contribution.id);
+    if (mode !== contribution.mode)
+      throw HookConfigurationError.make({
+        reason: "incompatible-transaction",
+        contribution: contribution.id,
+      });
+    contribution.validate?.();
+  }
+};
+
+export const interactiveContribution = <E, R>(
+  id: string,
+  run: (snapshot: LifecycleSnapshot) => Effect.Effect<void, E, R>,
+) => Object.freeze({ id, mode: "interactive" as const, run });
+
+/** The native owner executes this Effect synchronously and rolls back failures or suspension. */
+export const synchronousContribution = <E, R>(
+  id: string,
+  run: (snapshot: LifecycleSnapshot) => Effect.Effect<void, E, R>,
+) => Object.freeze({ id, mode: "synchronous" as const, run });
+
+/** Pure statement planning only; the consumer supplies and executes the actual atomic batch. */
+export const batchContribution = <Statement>(
+  id: string,
+  statements: (snapshot: LifecycleSnapshot) => ReadonlyArray<Statement>,
+) => Object.freeze({ id, mode: "batch" as const, statements });

package/src/http/auth-api.ts

@@ -0,0 +1,17 @@
+import { HttpApiGroup } from "effect/unstable/httpapi";
+
+import { GetSessionEndpoint } from "./endpoints/get-session";
+import { PasswordSignInEndpoint } from "./endpoints/password-sign-in";
+import { RequestEmailOtpEndpoint } from "./endpoints/request-email-otp";
+import { SetPasswordEndpoint } from "./endpoints/set-password";
+import { SignOutEndpoint } from "./endpoints/sign-out";
+import { VerifyEmailOtpEndpoint } from "./endpoints/verify-email-otp";
+
+export const AuthApi = HttpApiGroup.make("auth").add(
+  RequestEmailOtpEndpoint,
+  VerifyEmailOtpEndpoint,
+  PasswordSignInEndpoint,
+  SetPasswordEndpoint,
+  GetSessionEndpoint,
+  SignOutEndpoint,
+);

package/src/http/auth-contract.ts

@@ -0,0 +1,148 @@
+import { Context, Option, Schema, SchemaAST } from "effect";
+import { HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
+
+import { OperationHttpConfigurationError } from "../http-operation/errors";
+import { RevealWire } from "../http-operation/private";
+import type { AnyAuthAction, AuthActions } from "../operations/actions";
+
+const transportFailure = <const Reasons extends readonly [string, ...string[]]>(
+  status: number,
+  reasons: Reasons,
+) =>
+  Schema.TaggedStruct("TransportFailure", { reason: Schema.Literals(reasons) }).annotate({
+    httpApiStatus: status,
+  });
+
+const transportErrors = [
+  transportFailure(400, [
+    "request",
+    "credentials",
+    "response",
+    "network",
+    "stale-response",
+    "private-output",
+  ]),
+  transportFailure(403, ["origin", "csrf"]),
+  transportFailure(404, ["not-found"]),
+  transportFailure(405, ["method"]),
+  transportFailure(413, ["too-large"]),
+  transportFailure(503, ["unavailable"]),
+] as const;
+
+class EndpointContract extends Context.Service<
+  EndpointContract,
+  {
+    readonly action: AnyAuthAction;
+    readonly original: Pick<
+      HttpApiEndpoint.Top,
+      "path" | "method" | "params" | "query" | "headers" | "payload" | "success" | "error"
+    >;
+  }
+>()("effect-auth/http/EndpointContract") {}
+
+/** Only middleware and annotations may wrap the generated endpoint contract. */
+export const matchesEndpoint = (actual: HttpApiEndpoint.Top, action: AnyAuthAction): boolean => {
+  const metadata = Context.getOption(actual.annotations, EndpointContract);
+
+  if (Option.isNone(metadata) || metadata.value.action !== action) return false;
+  const expected = metadata.value.original;
+
+  return (
+    actual.path === expected.path &&
+    actual.method === expected.method &&
+    actual.params === expected.params &&
+    actual.query === expected.query &&
+    actual.headers === expected.headers &&
+    actual.payload === expected.payload &&
+    actual.success === expected.success &&
+    actual.error === expected.error
+  );
+};
+
+const endpoint = <const Name extends string, A extends AnyAuthAction>(name: Name, action: A) => {
+  const rpc = action.route.operation.rpc;
+
+  const encodedPayload = Schema.toEncoded<A["route"]["operation"]["rpc"]["payloadSchema"]>(
+    rpc.payloadSchema,
+  );
+
+  const encodedSuccess = Schema.toEncoded<A["route"]["operation"]["rpc"]["successSchema"]>(
+    rpc.successSchema,
+  );
+
+  const noPayload =
+    SchemaAST.isVoid(encodedPayload.ast) || SchemaAST.isUndefined(encodedPayload.ast);
+
+  const optionalPayload = Schema.is(encodedPayload)(undefined);
+  const noValue = SchemaAST.isVoid(encodedSuccess.ast) || SchemaAST.isUndefined(encodedSuccess.ast);
+  const optionalValue = Schema.is(encodedSuccess)(undefined);
+
+  const payload = noPayload
+    ? Schema.Struct({})
+    : optionalPayload
+      ? Schema.Struct({ payload: Schema.optionalKey(encodedPayload) })
+      : Schema.Struct({ payload: encodedPayload });
+
+  const privateOutput = Schema.optionalKey(Schema.Array(RevealWire));
+
+  const success = noValue
+    ? action.route.reveals.length === 0
+      ? Schema.TaggedStruct("Success", {})
+      : Schema.TaggedStruct("Success", { private: privateOutput })
+    : optionalValue
+      ? action.route.reveals.length === 0
+        ? Schema.TaggedStruct("Success", { value: Schema.optionalKey(encodedSuccess) })
+        : Schema.TaggedStruct("Success", {
+            value: Schema.optionalKey(encodedSuccess),
+            private: privateOutput,
+          })
+      : action.route.reveals.length === 0
+        ? Schema.TaggedStruct("Success", { value: encodedSuccess })
+        : Schema.TaggedStruct("Success", { value: encodedSuccess, private: privateOutput });
+
+  const failure = Schema.TaggedStruct("Failure", {
+    error: Schema.toEncoded<A["route"]["operation"]["rpc"]["errorSchema"]>(rpc.errorSchema),
+  }).annotate({ httpApiStatus: 400 });
+
+  const definition =
+    action.route.method === "GET"
+      ? HttpApiEndpoint.get(name, action.route.path, {
+          success,
+          error: [failure, ...transportErrors],
+        })
+      : HttpApiEndpoint.post(name, action.route.path, {
+          payload: Schema.toEncoded(payload),
+          success: Schema.toEncoded(success),
+          error: [Schema.toEncoded(failure), ...transportErrors],
+        });
+
+  return definition.annotate(EndpointContract, { action, original: definition });
+};
+
+type Endpoints<Actions extends AuthActions> = {
+  readonly [Name in keyof Actions]: ReturnType<
+    typeof endpoint<Extract<Name, string>, Actions[Name]>
+  >;
+}[keyof Actions];
+
+/** Native HttpApi projection of the named transport. Public envelopes are exact;
+ * private credentials remain cookies/headers, and private reveals retain their envelope.
+ * Server handlers use the same bounded operation decoder before schema projection.
+ */
+export const httpGroup = <Actions extends AuthActions, const Name extends string = "auth">(
+  contract: { readonly actions: Actions },
+  options?: { readonly name?: Name },
+) => {
+  const name = (options?.name ?? "auth") as Name;
+
+  // Entries preserve each descriptor's name/schema pairing; iteration erases that relationship.
+  const endpoints = Object.entries(contract.actions).map(([name, action]) =>
+    endpoint(name, action),
+  ) as Endpoints<Actions>[];
+
+  const first = endpoints[0];
+
+  if (first === undefined) throw OperationHttpConfigurationError.make({ reason: "route" });
+
+  return HttpApiGroup.make(name).add(first, ...endpoints.slice(1));
+};