@yielded/auth 0.1.0-beta.1

package/src/http/security.ts

@@ -0,0 +1,102 @@
+import { type Redacted, Context } from "effect";
+import { HttpApiMiddleware, HttpApiSecurity } from "effect/unstable/httpapi";
+
+import { AuthUnavailable, InvalidEmailOtp, InvalidRegistration, Unauthorized } from "../Errors";
+import type { CurrentSession } from "../internal/CurrentSession";
+import type { PendingRegistration } from "../Schema";
+
+export { CurrentSession } from "../internal/CurrentSession";
+
+export const challengeCookieName = "__Host-effect-auth-challenge";
+export const registrationCookieName = "__Host-effect-auth-registration";
+export const sessionCookieName = "__Host-effect-auth-session";
+
+/**
+ * Response header mirroring the session token whenever a session cookie is
+ * set. Native clients cannot read HttpOnly cookies (and refuse `Secure`
+ * cookies over plain http in development), so they store this value and send
+ * it back as `Authorization: Bearer <token>`. Same convention as BetterAuth's
+ * bearer plugin.
+ */
+export const authTokenHeaderName = "set-auth-token";
+/**
+ * Header twins of the challenge and registration cookies, for the same
+ * cookie-less clients the bearer transport serves. The sign-in flow spans
+ * requests (request code → verify → maybe register), and each hop's
+ * intermediate token otherwise rides a SameSite cookie the client never
+ * carries. Responses mirror the token in `set-auth-*`; clients echo it back
+ * in the matching `x-auth-*` request header.
+ */
+export const authChallengeHeaderName = "set-auth-challenge";
+export const authRegistrationHeaderName = "set-auth-registration";
+export const challengeHeaderName = "x-auth-challenge";
+export const registrationHeaderName = "x-auth-registration";
+
+export const SessionSecurity = HttpApiSecurity.apiKey({ key: sessionCookieName, in: "cookie" });
+/** Bearer transport for the same session token the cookie carries. */
+export const SessionBearerSecurity = HttpApiSecurity.bearer;
+
+export const ChallengeSecurity = HttpApiSecurity.apiKey({
+  key: challengeCookieName,
+  in: "cookie",
+});
+
+export const ChallengeHeaderSecurity = HttpApiSecurity.apiKey({
+  key: challengeHeaderName,
+  in: "header",
+});
+
+export const RegistrationSecurity = HttpApiSecurity.apiKey({
+  key: registrationCookieName,
+  in: "cookie",
+});
+
+export const RegistrationHeaderSecurity = HttpApiSecurity.apiKey({
+  key: registrationHeaderName,
+  in: "header",
+});
+
+export class CurrentRegistration extends Context.Service<
+  CurrentRegistration,
+  {
+    readonly registration: PendingRegistration;
+    readonly token: Redacted.Redacted<string>;
+  }
+>()("effect-auth/http/CurrentRegistration") {}
+
+export class CurrentChallenge extends Context.Service<
+  CurrentChallenge,
+  Redacted.Redacted<string>
+>()("effect-auth/http/CurrentChallenge") {}
+
+// These cookies are HttpOnly browser credentials, so generated clients do not
+// inject them. The transport layer carries them with same-origin requests.
+// Sessions additionally accept the same token as an `Authorization: Bearer`
+// header for clients without a usable cookie store; the securities are tried
+// in record order and the first one whose handler succeeds wins.
+export class SessionMiddleware extends HttpApiMiddleware.Service<
+  SessionMiddleware,
+  { provides: CurrentSession }
+>()("effect-auth/http/SessionMiddleware", {
+  security: { session: SessionSecurity, sessionBearer: SessionBearerSecurity },
+  error: [Unauthorized, AuthUnavailable],
+}) {}
+
+export class RegistrationMiddleware extends HttpApiMiddleware.Service<
+  RegistrationMiddleware,
+  { provides: CurrentRegistration }
+>()("effect-auth/http/RegistrationMiddleware", {
+  security: {
+    registration: RegistrationSecurity,
+    registrationHeader: RegistrationHeaderSecurity,
+  },
+  error: [InvalidRegistration, AuthUnavailable],
+}) {}
+
+export class ChallengeMiddleware extends HttpApiMiddleware.Service<
+  ChallengeMiddleware,
+  { provides: CurrentChallenge }
+>()("effect-auth/http/ChallengeMiddleware", {
+  security: { challenge: ChallengeSecurity, challengeHeader: ChallengeHeaderSecurity },
+  error: [InvalidEmailOtp],
+}) {}

package/src/http/session-contract.ts

@@ -0,0 +1,92 @@
+import { Context, type Schema, type Types } from "effect";
+import type { HttpRouter } from "effect/unstable/http";
+import { HttpApiMiddleware, HttpApiSecurity } from "effect/unstable/httpapi";
+
+import type { AuthRequest } from "../auth/AuthRequest";
+import { HookDenied } from "../hooks/models";
+import {
+  AuthenticationRequired,
+  AssuranceRequired,
+  OperationBoundaryError,
+  OperationForbidden,
+} from "../operations/errors";
+import {
+  SessionError,
+  SessionInvalid,
+  SessionSignOutUnavailable,
+  SessionUnavailable,
+} from "../sessions/errors";
+
+/** Existing domain failures with HTTP statuses, without changing their wire values. */
+const sessionHttpErrors = [
+  ...SessionError.members.map((member) =>
+    member.annotate({
+      httpApiStatus:
+        member === SessionInvalid
+          ? 401
+          : member === SessionUnavailable || member === SessionSignOutUnavailable
+            ? 503
+            : 400,
+    }),
+  ),
+  ...OperationBoundaryError.members.map((member) =>
+    member.annotate({
+      httpApiStatus:
+        member === AuthenticationRequired
+          ? 401
+          : member === OperationForbidden || member === AssuranceRequired
+            ? 403
+            : 400,
+    }),
+  ),
+  HookDenied.annotate({ httpApiStatus: 403 }),
+];
+
+export interface SessionHttpService<Id extends string, Kind extends string, Session> {
+  readonly namespace: Id;
+  readonly kind: Kind;
+  readonly session: Types.Invariant<Session>;
+}
+
+export type SessionHttpAuthorization<Id extends string, Session> = SessionHttpService<
+  Id,
+  "require",
+  Session
+> & {
+  readonly [Key in keyof HttpApiMiddleware.AnyId]: {
+    readonly provides: SessionHttpService<Id, "session", Session>;
+    readonly requires: HttpRouter.Request.From<"Requires", AuthRequest>;
+    readonly error: typeof sessionHttpErrors;
+    readonly clientError: never;
+    readonly requiredForClient: false;
+  };
+};
+
+/** Shared HttpApi security metadata and authenticated session service.
+ * The server implementation requires the validated request supplied by AuthHttp.middleware.
+ * Keep this declaration beside the application's shared API, outside server setup.
+ */
+export const makeSessionHttpContract = <const Id extends string, S extends Schema.Top>(
+  id: Id,
+  session: S,
+  options: { readonly cookieName: string },
+) => {
+  const cookieName = options.cookieName;
+
+  const CurrentSession = Context.Service<SessionHttpService<Id, "session", S["Type"]>, S["Type"]>(
+    `${id}/CurrentSession`,
+  );
+
+  const RequireSession = HttpApiMiddleware.Service<
+    SessionHttpAuthorization<Id, S["Type"]>,
+    {
+      provides: SessionHttpService<Id, "session", S["Type"]>;
+      requires: HttpRouter.Request.From<"Requires", AuthRequest>;
+    }
+  >()(`${id}/RequireSession`, {
+    security: { session: HttpApiSecurity.apiKey({ in: "cookie", key: cookieName }) },
+    error: sessionHttpErrors,
+  });
+
+  return Object.freeze({ id, CurrentSession, RequireSession, session, cookieName });
+};

package/src/http-operation/OperationHttpInvocation.ts

@@ -0,0 +1,39 @@
+import { Context, Effect, Layer } from "effect";
+
+import type { SessionApiError } from "../auth/session";
+import type { AuthInvocation } from "../operations/context";
+import type { OperationHttpError } from "./errors";
+import type { HttpCredentials } from "./models";
+
+export class OperationHttpInvocation extends Context.Service<
+  OperationHttpInvocation,
+  {
+    /** A public action resolves caller identity only when its local method needs it. */
+    readonly request?: (
+      request: Request,
+      credentials: HttpCredentials,
+    ) => Effect.Effect<AuthInvocation, SessionApiError>;
+    readonly resolve: (
+      request: Request,
+      credentials: HttpCredentials,
+    ) => Effect.Effect<AuthInvocation, OperationHttpError>;
+  }
+>()("effect-auth/OperationHttpInvocation") {}
+
+export const invocationLayer = <R>(
+  resolve: (
+    request: Request,
+    credentials: HttpCredentials,
+  ) => Effect.Effect<AuthInvocation, OperationHttpError, R>,
+) =>
+  Layer.effect(
+    OperationHttpInvocation,
+    Effect.gen(function* () {
+      const services = yield* Effect.context<R>();
+
+      return {
+        resolve: (request: Request, credentials: HttpCredentials) =>
+          resolve(request, credentials).pipe(Effect.provide(services)),
+      };
+    }),
+  );

package/src/http-operation/OperationHttpServerConfig.ts

@@ -0,0 +1,124 @@
+import { Context, Effect, Layer, Schema } from "effect";
+import { Cookies } from "effect/unstable/http";
+
+import type { CredentialSlot } from "../operations/credentials";
+import { headerName, origin } from "./configuration-schema";
+import { OperationHttpConfigurationError } from "./errors";
+import { credentialSlots, type OperationCookie, type OperationHttpConfiguration } from "./models";
+
+export class OperationHttpServerConfig extends Context.Service<
+  OperationHttpServerConfig,
+  OperationHttpConfiguration
+>()("effect-auth/OperationHttpServerConfig") {}
+
+const cookie = Schema.Struct({
+  name: Schema.NonEmptyString,
+  path: Schema.String.check(Schema.isStartsWith("/")),
+  secure: Schema.Boolean,
+  sameSite: Schema.Literals(["lax", "strict", "none"]),
+  domain: Schema.optionalKey(Schema.String),
+});
+
+export const configurationLayer = (input: OperationHttpConfiguration) =>
+  Layer.effect(
+    OperationHttpServerConfig,
+    Effect.try({
+      try: () => {
+        if (
+          input.trustedOrigins.length === 0 ||
+          !input.trustedOrigins.every(Schema.is(origin)) ||
+          !Schema.is(headerName)(input.csrfHeader) ||
+          input.csrfValue.length < 1 ||
+          input.csrfValue.length > 128 ||
+          !Number.isSafeInteger(input.maximumBodyBytes) ||
+          input.maximumBodyBytes < 1 ||
+          input.maximumBodyBytes > 1048576 ||
+          !Number.isSafeInteger(input.maximumUrlBytes) ||
+          input.maximumUrlBytes < 1 ||
+          input.maximumUrlBytes > 16384
+        )
+          throw new Error();
+        if (typeof input.publicOrigin === "string" && !Schema.is(origin)(input.publicOrigin))
+          throw new Error();
+        const names = new Set<string>();
+
+        const cookies = Object.fromEntries(
+          credentialSlots.map((slot) => {
+            const value = Schema.decodeSync(cookie)(input.cookies[slot]);
+
+            if (
+              names.has(value.name) ||
+              (value.sameSite === "none" && !value.secure) ||
+              (value.name.startsWith("__Secure-") && !value.secure) ||
+              (value.name.startsWith("__Host-") &&
+                (!value.secure || value.path !== "/" || value.domain !== undefined))
+            )
+              throw new Error();
+            names.add(value.name);
+            Cookies.makeCookieUnsafe(value.name, "probe", { ...value, httpOnly: true });
+
+            return [slot, Object.freeze(value)];
+          }),
+        ) as unknown as OperationHttpConfiguration["cookies"];
+
+        if (input.native !== undefined) {
+          const native = input.native;
+
+          const request = [
+            native.modeHeader,
+            ...credentialSlots.map((slot) => native.requestHeaders[slot]),
+          ];
+
+          const response = credentialSlots.map((slot) => native.responseHeaders[slot]);
+
+          if (
+            [...request, ...response].some((name) => !Schema.is(headerName)(name)) ||
+            new Set(request).size !== request.length ||
+            new Set(response).size !== response.length ||
+            request.some((name) => ["origin", "cookie", "host", input.csrfHeader].includes(name)) ||
+            response.some((name) => ["set-cookie", "location", "content-type"].includes(name))
+          )
+            throw new Error();
+        }
+
+        return Object.freeze({
+          ...input,
+          cookies,
+          trustedOrigins: Object.freeze([...input.trustedOrigins]),
+          ...(input.native === undefined
+            ? {}
+            : {
+                native: Object.freeze({
+                  ...input.native,
+                  requestHeaders: Object.freeze({ ...input.native.requestHeaders }),
+                  responseHeaders: Object.freeze({ ...input.native.responseHeaders }),
+                }),
+              }),
+        });
+      },
+      catch: () => OperationHttpConfigurationError.make({ reason: "cookies" }),
+    }),
+  );
+
+export const cookieConfiguration = (input: {
+  readonly prefix: string;
+  readonly secure: boolean;
+  readonly path?: string;
+  readonly sameSite?: OperationCookie["sameSite"];
+}): OperationHttpConfiguration["cookies"] =>
+  Object.fromEntries(
+    credentialSlots.map((slot) => [
+      slot,
+      {
+        name: `${input.prefix}${slot}`,
+        path: input.path ?? "/",
+        secure: input.secure,
+        sameSite: input.sameSite ?? "lax",
+      },
+    ]),
+  ) as unknown as OperationHttpConfiguration["cookies"];
+
+export const headerConfiguration = (prefix: string): Readonly<Record<CredentialSlot, string>> =>
+  Object.fromEntries(credentialSlots.map((slot) => [slot, `${prefix}${slot}`])) as Readonly<
+    Record<CredentialSlot, string>
+  >;

package/src/http-operation/auth-client.ts

@@ -0,0 +1,273 @@
+import { Context, Effect, Layer, Scope, Semaphore } from "effect";
+
+import type { AnyAuthAction, AuthActions } from "../operations/actions";
+import {
+  makeAuthenticationCompletion,
+  make as makeTransport,
+  type OperationAuthenticationCompletion,
+  type OperationFetchClient,
+  type OperationFetchOptions,
+} from "./client";
+import type { RouteFailure, RouteInput, RouteSuccess } from "./contract";
+import { OperationHttpError } from "./errors";
+
+export type ClientOptions = Omit<OperationFetchOptions, "csrfHeader" | "csrfValue"> & {
+  readonly csrf?: { readonly header: string; readonly value: string };
+};
+
+export type ActionDecodeServices<Action extends AnyAuthAction> =
+  | Action["route"]["operation"]["rpc"]["successSchema"]["DecodingServices"]
+  | Action["route"]["operation"]["rpc"]["errorSchema"]["DecodingServices"];
+
+export type ActionArguments<Action extends AnyAuthAction> =
+  undefined extends RouteInput<Action["route"]>
+    ? readonly [input?: RouteInput<Action["route"]>]
+    : readonly [input: RouteInput<Action["route"]>];
+
+export interface AuthClientState {
+  readonly subject: string | null;
+  readonly generation: number;
+}
+
+export type AuthClientEvent =
+  | {
+      readonly _tag: "Transition";
+      readonly state: AuthClientState;
+      readonly action?: string;
+      readonly origin?: object;
+    }
+  | { readonly _tag: "Mutation"; readonly name: string };
+
+/** Internal bridge shared with Atom. Subscriptions belong to their host Scope;
+ * transition listeners only dispose and publish state, never call the client. */
+export interface AuthClientController<Actions extends AuthActions> {
+  readonly actions: Actions;
+  readonly transport: OperationFetchClient;
+  readonly state: Effect.Effect<AuthClientState>;
+  readonly subscribe: (
+    listener: (event: AuthClientEvent) => Effect.Effect<void>,
+  ) => Effect.Effect<void, never, Scope.Scope>;
+  readonly replaceSubject: (subject: string | null) => Effect.Effect<void>;
+  readonly completeAuthentication: OperationAuthenticationCompletion;
+  readonly call: <Name extends keyof Actions>(
+    name: Name,
+    input: RouteInput<Actions[Name]["route"]>,
+    options?: { readonly notifyMutation?: boolean; readonly origin?: object },
+  ) => Effect.Effect<
+    RouteSuccess<Actions[Name]["route"]>,
+    RouteFailure<Actions[Name]["route"]> | OperationHttpError,
+    ActionDecodeServices<Actions[Name]>
+  >;
+}
+
+export const AuthClientTypeId: unique symbol = Symbol.for("effect-auth/Client");
+
+/** Named calls return Effects; request credentials and private reveals remain
+ * in the configured transport capabilities, outside operation results. */
+export type AuthClient<Actions extends AuthActions> = {
+  readonly [Name in keyof Actions]: (
+    ...args: ActionArguments<Actions[Name]>
+  ) => Effect.Effect<
+    RouteSuccess<Actions[Name]["route"]>,
+    RouteFailure<Actions[Name]["route"]> | OperationHttpError,
+    ActionDecodeServices<Actions[Name]>
+  >;
+} & { readonly [AuthClientTypeId]: AuthClientController<Actions> };
+
+/** Derive one named client from the shared contract. Each operation makes one
+ * attempt. Authentication transitions also notify any scoped Atom consumers. */
+const acquire = Effect.fn("Client.make")(function* <Actions extends AuthActions>(
+  contract: { readonly actions: Actions },
+  options: ClientOptions,
+): Effect.fn.Return<{ readonly auth: AuthClient<Actions> }, OperationHttpError, Scope.Scope> {
+  const transport = yield* makeTransport({
+    ...options,
+    csrfHeader: options.csrf?.header ?? "x-effect-auth-csrf",
+    csrfValue: options.csrf?.value ?? "1",
+  });
+
+  const gate = yield* Semaphore.make(1);
+  const listeners = new Set<(event: AuthClientEvent) => Effect.Effect<void>>();
+  let state: AuthClientState = { subject: null, generation: 0 };
+  let closed = false;
+
+  const notify = (event: AuthClientEvent) =>
+    Effect.forEach([...listeners], (listener) => listener(event), {
+      concurrency: 1,
+      discard: true,
+    });
+
+  const publish = Effect.fn("Client.publishSubject")(function* (
+    subject: string | null,
+    action?: string,
+    origin?: object,
+  ) {
+    state = { subject, generation: state.generation + 1 };
+    yield* notify({
+      _tag: "Transition",
+      state,
+      ...(action === undefined ? {} : { action }),
+      ...(origin === undefined ? {} : { origin }),
+    });
+  });
+
+  const completeAuthentication = makeAuthenticationCompletion(transport, gate, publish);
+
+  const replaceSubject = Effect.fn("Client.replaceSubject")(function* (subject: string | null) {
+    yield* gate.withPermits(1)(
+      Effect.uninterruptible(
+        Effect.gen(function* () {
+          yield* transport.transition;
+          yield* publish(subject);
+        }),
+      ),
+    );
+  });
+
+  const call: AuthClientController<Actions>["call"] = Effect.fn("Client.call")(function* <
+    Name extends keyof Actions,
+  >(
+    name: Name,
+    input: RouteInput<Actions[Name]["route"]>,
+    callOptions?: { readonly notifyMutation?: boolean; readonly origin?: object },
+  ) {
+    if (closed) return yield* OperationHttpError.make({ reason: "stale-response" });
+
+    const action = contract.actions[name];
+    const project = action.subject;
+    const started = yield* transport.generation;
+    let transitioned = false;
+
+    const execute = Effect.gen(function* () {
+      if (project !== undefined && action.mode === "mutation") {
+        const generation = state.generation;
+
+        // Notify within credential settlement: disposing an account registry can
+        // interrupt the atom that dispatched this call before a later success tap.
+        const complete = makeAuthenticationCompletion(transport, gate, (subject) =>
+          publish(subject, String(name), callOptions?.origin),
+        );
+
+        const value = yield* complete<Actions[Name]["route"]>(action.route, input, (success) =>
+          project.fromSuccess(success),
+        );
+
+        transitioned = state.generation !== generation;
+
+        return value;
+      }
+
+      const value = yield* transport.call<Actions[Name]["route"]>(action.route, input);
+
+      if (project !== undefined) {
+        yield* gate.withPermits(1)(
+          Effect.uninterruptible(
+            Effect.gen(function* () {
+              if ((yield* transport.generation) !== started)
+                return yield* OperationHttpError.make({ reason: "stale-response" });
+
+              const subject = yield* Effect.try({
+                try: () => project.fromSuccess(value),
+                catch: () => OperationHttpError.make({ reason: "response" }),
+              });
+
+              if (subject !== undefined && subject !== state.subject) {
+                yield* transport.transition;
+                yield* publish(subject);
+              }
+            }),
+          ),
+        );
+      }
+
+      return value;
+    });
+
+    const value = yield* execute;
+
+    if (action.mode === "mutation" && !transitioned && callOptions?.notifyMutation !== false)
+      yield* notify({ _tag: "Mutation", name: String(name) });
+
+    return value;
+  });
+
+  const controller: AuthClientController<Actions> = {
+    actions: contract.actions,
+    transport,
+    state: Effect.sync(() => state),
+    call,
+    replaceSubject,
+    completeAuthentication,
+    subscribe: (listener) =>
+      Effect.acquireRelease(
+        gate.withPermits(1)(
+          Effect.gen(function* () {
+            yield* listener({ _tag: "Transition", state });
+            listeners.add(listener);
+          }),
+        ),
+        () => Effect.sync(() => void listeners.delete(listener)),
+      ),
+  };
+
+  yield* Scope.addFinalizer(
+    yield* Effect.scope,
+    gate.withPermits(1)(
+      Effect.gen(function* () {
+        closed = true;
+        yield* transport.transition;
+        listeners.clear();
+      }),
+    ),
+  );
+
+  const methods = Object.fromEntries(
+    Object.keys(contract.actions).map((name) => [
+      name,
+      (input: RouteInput<Actions[string]["route"]>) => call(name, input),
+    ]),
+  );
+
+  Object.defineProperty(methods, AuthClientTypeId, { value: controller });
+
+  // Every property delegates to the same named contract entry. This cast restores
+  // the mapped key/signature relationship after constructing the property table.
+  return { auth: Object.freeze(methods) as AuthClient<Actions> };
+});
+
+/** Identifier for a configured client service, separate from the server service. */
+export interface ClientService<Id extends string, Actions extends AuthActions> {
+  readonly namespace: Id;
+  readonly actions: Actions;
+  readonly _client: unique symbol;
+}
+
+export interface ClientDefinition<
+  Id extends string,
+  Actions extends AuthActions,
+> extends Context.Service<ClientService<Id, Actions>, { readonly auth: AuthClient<Actions> }> {
+  readonly contract: { readonly namespace: Id; readonly actions: Actions };
+  readonly make: Effect.Effect<
+    { readonly auth: AuthClient<Actions> },
+    OperationHttpError,
+    Scope.Scope
+  >;
+  readonly layer: Layer.Layer<ClientService<Id, Actions>, OperationHttpError>;
+}
+
+/** Define a yieldable client without acquiring resources. Provide its layer once
+ * in the application Scope, or yield its make Effect for direct acquisition.
+ * Every instance owns its credential settlement and scoped Atom subscriptions. */
+export const make = <const Id extends string, Actions extends AuthActions>(
+  contract: { readonly namespace: Id; readonly actions: Actions },
+  options: ClientOptions,
+): ClientDefinition<Id, Actions> => {
+  const service = Context.Service<
+    ClientService<Id, Actions>,
+    { readonly auth: AuthClient<Actions> }
+  >()(`${contract.namespace}/client`);
+
+  const create = acquire(contract, options);
+
+  return Object.assign(service, { contract, make: create, layer: Layer.effect(service, create) });
+};