@yielded/auth 0.1.0-beta.1

package/src/AuthTokenCodec.ts

@@ -0,0 +1,226 @@
+import { Context, Crypto, Effect, Encoding, Layer, Redacted, Result, Schema } from "effect";
+
+import { AuthTokenError, InvalidSession } from "./Errors";
+import {
+  KeyedDigest,
+  type KeyId,
+  OtpDigest,
+  SessionClaims,
+  SessionToken,
+  TokenDigest,
+} from "./Schema";
+import { SubtleCrypto } from "./WebCrypto";
+
+/**
+ * HMAC keyring: one active signing key plus verification keys retained until
+ * their sessions expire. Every secret must hold at least 256 random bits.
+ */
+export class AuthKeyring extends Context.Service<
+  AuthKeyring,
+  {
+    readonly activeKeyId: KeyId;
+    readonly keys: ReadonlyArray<{
+      readonly keyId: KeyId;
+      readonly secret: Redacted.Redacted<string>;
+    }>;
+  }
+>()("effect-auth/AuthKeyring") {}
+
+export interface AuthTokenCodecService {
+  readonly activeKeyId: KeyId;
+  /** Active key first, then verification-only keys. */
+  readonly keyIds: ReadonlyArray<KeyId>;
+  readonly encodeSession: (claims: SessionClaims) => Effect.Effect<SessionToken, AuthTokenError>;
+  /** Checks format, key id, and signature. Time and policy checks belong to `AuthSession`. */
+  readonly decodeSession: (
+    token: Redacted.Redacted<string>,
+  ) => Effect.Effect<SessionClaims, InvalidSession | AuthTokenError>;
+  /** Unkeyed digest for high-entropy tokens; stable across key rotation. */
+  readonly digestToken: (
+    token: Redacted.Redacted<string>,
+    scope: string,
+  ) => Effect.Effect<TokenDigest, AuthTokenError>;
+  /** Keyed digest for low-entropy secrets, scoped so digests cannot be transplanted. */
+  readonly digestSecret: (
+    value: Redacted.Redacted<string>,
+    scope: string,
+    keyId?: KeyId,
+  ) => Effect.Effect<KeyedDigest, AuthTokenError>;
+}
+
+const envelopeVersion = "eav1";
+const textEncoder = new TextEncoder();
+
+// One JSON-string codec owns the token payload text, both directions. Plain
+// `fromJsonString` (no `toCodecJson`): the opaque `ext` claims slot keeps
+// native `JSON.stringify` semantics.
+const SessionClaimsJson = Schema.fromJsonString(SessionClaims);
+const encodeClaimsJson = Schema.encodeEffect(SessionClaimsJson);
+const decodeClaimsJson = Schema.decodeEffect(SessionClaimsJson);
+const tokenDigestFromString = Schema.decodeEffect(TokenDigest);
+const otpDigestFromString = Schema.decodeEffect(OtpDigest);
+const sessionTokenFromString = Schema.decodeEffect(SessionToken);
+
+/**
+ * Default HMAC-SHA-256 codec on WebCrypto. Signing keys never leave the
+ * runtime's key store; secure random bytes come from `Crypto.Crypto`.
+ */
+const makeWebCryptoCodec: Effect.Effect<
+  AuthTokenCodecService,
+  AuthTokenError,
+  AuthKeyring | Crypto.Crypto | SubtleCrypto
+> = Effect.gen(function* () {
+  const keyring = yield* AuthKeyring;
+  const crypto = yield* Crypto.Crypto;
+  const subtle = yield* SubtleCrypto;
+
+  if (!keyring.keys.some((key) => key.keyId === keyring.activeKeyId)) {
+    return yield* AuthTokenError.make({
+      message: "Keyring does not contain the active signing key",
+    });
+  }
+
+  const importKey = (secret: Redacted.Redacted<string>) =>
+    Effect.tryPromise({
+      try: () =>
+        subtle.importKey(
+          "raw",
+          textEncoder.encode(Redacted.value(secret)),
+          { name: "HMAC", hash: "SHA-256" },
+          false,
+          ["sign", "verify"],
+        ),
+      catch: () => AuthTokenError.make({ message: "Failed to import HMAC key" }),
+    });
+
+  const keys = new Map<KeyId, CryptoKey>();
+
+  for (const entry of keyring.keys) {
+    keys.set(entry.keyId, yield* importKey(entry.secret));
+  }
+
+  const hmac = (keyId: KeyId, data: Uint8Array) =>
+    Effect.gen(function* () {
+      const key = keys.get(keyId);
+
+      if (key === undefined) {
+        return yield* AuthTokenError.make({ message: "Unknown key id" });
+      }
+
+      const signature = yield* Effect.tryPromise({
+        try: () => subtle.sign("HMAC", key, data as BufferSource),
+        catch: () => AuthTokenError.make({ message: "HMAC signing failed" }),
+      });
+
+      return new Uint8Array(signature);
+    });
+
+  const hmacVerify = (keyId: KeyId, data: Uint8Array, signature: Uint8Array) =>
+    Effect.gen(function* () {
+      const key = keys.get(keyId);
+
+      if (key === undefined) {
+        return false;
+      }
+
+      return yield* Effect.tryPromise({
+        try: () => subtle.verify("HMAC", key, signature as BufferSource, data as BufferSource),
+        catch: () => AuthTokenError.make({ message: "HMAC verification failed" }),
+      });
+    });
+
+  return {
+    activeKeyId: keyring.activeKeyId,
+    keyIds: [
+      keyring.activeKeyId,
+      ...keyring.keys.map((key) => key.keyId).filter((id) => id !== keyring.activeKeyId),
+    ],
+
+    encodeSession: Effect.fn("AuthTokenCodec.encodeSession")(function* (claims) {
+      const encoded = yield* encodeClaimsJson(claims).pipe(
+        Effect.mapError(() => AuthTokenError.make({ message: "Session claims failed to encode" })),
+      );
+
+      const payload = Encoding.encodeBase64Url(encoded);
+      const signingInput = `${envelopeVersion}.${payload}`;
+      const signature = yield* hmac(claims.kid, textEncoder.encode(signingInput));
+      const token = `${signingInput}.${Encoding.encodeBase64Url(signature)}`;
+
+      return yield* sessionTokenFromString(token).pipe(
+        Effect.mapError(() => AuthTokenError.make({ message: "Session token failed to encode" })),
+      );
+    }),
+
+    decodeSession: Effect.fn("AuthTokenCodec.decodeSession")(function* (token) {
+      const [version, payloadPart, signaturePart, ...rest] = Redacted.value(token).split(".");
+
+      if (
+        version !== envelopeVersion ||
+        payloadPart === undefined ||
+        signaturePart === undefined ||
+        rest.length > 0
+      ) {
+        return yield* InvalidSession.make();
+      }
+      const payloadJson = Result.getOrUndefined(Encoding.decodeBase64UrlString(payloadPart));
+      const signature = Result.getOrUndefined(Encoding.decodeBase64Url(signaturePart));
+
+      if (payloadJson === undefined || signature === undefined) {
+        return yield* InvalidSession.make();
+      }
+
+      const claims = yield* decodeClaimsJson(payloadJson).pipe(
+        Effect.mapError(() => InvalidSession.make()),
+      );
+
+      const signingInput = `${envelopeVersion}.${payloadPart}`;
+      const valid = yield* hmacVerify(claims.kid, textEncoder.encode(signingInput), signature);
+
+      if (!valid) {
+        return yield* InvalidSession.make();
+      }
+
+      return claims;
+    }),
+
+    digestToken: Effect.fn("AuthTokenCodec.digestToken")(function* (token, scope) {
+      const data = textEncoder.encode(`${scope}\n${Redacted.value(token)}`);
+
+      const digest = yield* crypto
+        .digest("SHA-256", data)
+        .pipe(Effect.mapError(() => AuthTokenError.make({ message: "Token digest failed" })));
+
+      return yield* tokenDigestFromString(Encoding.encodeBase64Url(digest)).pipe(
+        Effect.mapError(() => AuthTokenError.make({ message: "Token digest failed to encode" })),
+      );
+    }),
+
+    digestSecret: Effect.fn("AuthTokenCodec.digestSecret")(function* (value, scope, keyId) {
+      const resolvedKeyId = keyId ?? keyring.activeKeyId;
+      const data = textEncoder.encode(`${scope}\n${Redacted.value(value)}`);
+      const digest = yield* hmac(resolvedKeyId, data);
+
+      const otpDigest = yield* otpDigestFromString(Encoding.encodeBase64Url(digest)).pipe(
+        Effect.mapError(() => AuthTokenError.make({ message: "Secret digest failed to encode" })),
+      );
+
+      return KeyedDigest.make({ keyId: resolvedKeyId, digest: otpDigest });
+    }),
+  };
+});
+
+export class AuthTokenCodec extends Context.Service<AuthTokenCodec, AuthTokenCodecService>()(
+  "effect-auth/AuthTokenCodec",
+) {
+  /**
+   * Default HMAC implementation backed by WebCrypto. The consumer may replace
+   * it with its own codec service.
+   */
+  static readonly layerWebCrypto: Layer.Layer<
+    AuthTokenCodec,
+    AuthTokenError,
+    AuthKeyring | Crypto.Crypto
+  > = Layer.effect(AuthTokenCodec)(makeWebCryptoCodec).pipe(Layer.provide(SubtleCrypto.layerWeb));
+
+  static readonly layer = AuthTokenCodec.layerWebCrypto;
+}

package/src/Client.ts

@@ -0,0 +1,9 @@
+export {
+  make,
+  type AuthClient,
+  type ClientOptions,
+  type ClientDefinition,
+  type ClientService,
+  type ActionArguments,
+  type ActionDecodeServices,
+} from "./http-operation/auth-client";

package/src/Cloudflare.ts

@@ -0,0 +1,345 @@
+import { DateTime, Duration, Effect, Layer, Redacted, Schema } from "effect";
+import {
+  type Binding,
+  type Environment,
+  DurableObject,
+  DurableObjectState,
+  Email,
+  Worker,
+} from "effect-cf";
+import type { OtlpExporter } from "effect/unstable/observability";
+
+import { AuthStore, AuthStoreBackend, EmailOtpRejected } from "./AuthStore";
+import { EmailOtpSender } from "./EmailOtpSender";
+import { AuthRateLimited, AuthStoreError, InvalidRegistration } from "./Errors";
+import {
+  type TokenDigest as TokenDigestType,
+  ConsumeChallenge,
+  ConsumeRegistration,
+  NewChallenge,
+  NewRegistration,
+  PendingRegistration,
+  TokenDigest,
+  VerifiedEmail,
+} from "./Schema";
+
+/**
+ * Typed RPC contract for the auth store Durable Object. A single named
+ * instance backs a deployment: auth traffic is low-rate, and one serialized
+ * object makes the store's exactly-once consume guarantees structural.
+ * Expected auth failures travel inside the success schemas; the worker-side
+ * client re-fails them.
+ */
+export class AuthStoreObject extends DurableObject.Tag<AuthStoreObject>()(
+  "effect-auth/AuthStoreObject",
+  {
+    issueChallenge: DurableObject.method({
+      args: [NewChallenge],
+      success: Schema.Union([Schema.Null, AuthRateLimited]),
+    }),
+    consumeChallenge: DurableObject.method({
+      args: [ConsumeChallenge],
+      success: Schema.Union([VerifiedEmail, EmailOtpRejected]),
+    }),
+    issueRegistration: DurableObject.method({
+      args: [NewRegistration],
+      success: Schema.Null,
+    }),
+    inspectRegistration: DurableObject.method({
+      args: [TokenDigest],
+      success: Schema.Union([PendingRegistration, InvalidRegistration]),
+    }),
+    consumeRegistration: DurableObject.method({
+      args: [ConsumeRegistration],
+      success: Schema.Union([Schema.Null, InvalidRegistration]),
+    }),
+  },
+) {}
+
+/**
+ * The canonical effect-auth store state machine over the object's own
+ * storage. The Durable Object's input gates serialize requests; the machine
+ * adds its own serialization on top, so exactly-once consumption holds
+ * regardless. Export this class from the worker entry module and register it
+ * under `durable_objects` in the wrangler configuration.
+ */
+const BackendLive = Layer.effect(AuthStoreBackend)(
+  Effect.map(DurableObjectState.DurableObjectState, (state) =>
+    AuthStoreBackend.of({
+      get: (key) =>
+        state.storage
+          .get(key)
+          .pipe(
+            Effect.mapError(() => AuthStoreError.make({ message: "Auth store storage failed" })),
+          ),
+      put: (key, value) =>
+        state.storage
+          .put(key, value)
+          .pipe(
+            Effect.mapError(() => AuthStoreError.make({ message: "Auth store storage failed" })),
+          ),
+      remove: (key) =>
+        state.storage.delete(key).pipe(
+          Effect.asVoid,
+          Effect.mapError(() => AuthStoreError.make({ message: "Auth store storage failed" })),
+        ),
+    }),
+  ),
+);
+
+// Expected auth failures travel inside the RPC success schemas; infrastructure
+// failures become defects and surface as transport errors on the caller side.
+const AuthStoreLive = AuthStore.layerBackend.pipe(Layer.provide(BackendLive));
+
+const AuthStoreDurableObjectOptions = {
+  rpc: {
+    issueChallenge: (input) =>
+      Effect.gen(function* () {
+        const store = yield* AuthStore;
+
+        return yield* store.issueChallenge(input).pipe(
+          Effect.as(null),
+          Effect.catchTags({
+            AuthRateLimited: (error) => Effect.succeed(error),
+            AuthStoreError: Effect.die,
+          }),
+        );
+      }),
+    consumeChallenge: (input) =>
+      Effect.gen(function* () {
+        const store = yield* AuthStore;
+
+        return yield* store.consumeChallenge(input).pipe(
+          Effect.catchTags({
+            EmailOtpRejected: (error) => Effect.succeed(error),
+            AuthStoreError: Effect.die,
+          }),
+        );
+      }),
+    issueRegistration: (input) =>
+      Effect.gen(function* () {
+        const store = yield* AuthStore;
+
+        yield* store.issueRegistration(input).pipe(Effect.catchTag("AuthStoreError", Effect.die));
+
+        return null;
+      }),
+    inspectRegistration: (tokenDigest: TokenDigestType) =>
+      Effect.gen(function* () {
+        const store = yield* AuthStore;
+
+        return yield* store.inspectRegistration(tokenDigest).pipe(
+          Effect.catchTags({
+            InvalidRegistration: (error) => Effect.succeed(error),
+            AuthStoreError: Effect.die,
+          }),
+        );
+      }),
+    consumeRegistration: (input) =>
+      Effect.gen(function* () {
+        const store = yield* AuthStore;
+
+        return yield* store.consumeRegistration(input).pipe(
+          Effect.as(null),
+          Effect.catchTags({
+            InvalidRegistration: (error) => Effect.succeed(error),
+            AuthStoreError: Effect.die,
+          }),
+        );
+      }),
+  },
+} satisfies DurableObject.Options<AuthStore, typeof AuthStoreObject>;
+
+/** Builds the auth store object with an application-owned OTLP telemetry layer. */
+export const makeAuthStoreDurableObject = (
+  telemetry: Layer.Layer<OtlpExporter.Flusher, never, DurableObjectState.DurableObjectState>,
+) => AuthStoreObject.make(Layer.merge(AuthStoreLive, telemetry), AuthStoreDurableObjectOptions);
+
+const clientUnavailable = () => AuthStoreError.unavailable;
+
+/**
+ * Worker-side `AuthStore` over the auth Durable Object binding. Swapping this
+ * layer for a different backing (Postgres, PlanetScale) is the intended
+ * migration path: implement the same `AuthStore` contract and rerun the
+ * conformance suite.
+ */
+export const layerAuthStoreClient: Layer.Layer<AuthStore, never, AuthStoreObject> = Layer.effect(
+  AuthStore,
+)(
+  Effect.map(AuthStoreObject, (objects) => {
+    const stub = objects.byName("primary");
+
+    return AuthStore.of({
+      issueChallenge: Effect.fn("AuthStoreObject.client.issueChallenge")(function* (input) {
+        const outcome = yield* stub.issueChallenge(input).pipe(Effect.mapError(clientUnavailable));
+
+        if (outcome !== null) {
+          return yield* outcome;
+        }
+      }),
+      consumeChallenge: Effect.fn("AuthStoreObject.client.consumeChallenge")(function* (input) {
+        const outcome = yield* stub
+          .consumeChallenge(input)
+          .pipe(Effect.mapError(clientUnavailable));
+
+        if ("_tag" in outcome) {
+          return yield* outcome;
+        }
+
+        return outcome;
+      }),
+      issueRegistration: Effect.fn("AuthStoreObject.client.issueRegistration")(function* (input) {
+        yield* stub.issueRegistration(input).pipe(Effect.mapError(clientUnavailable));
+      }),
+      inspectRegistration: Effect.fn("AuthStoreObject.client.inspectRegistration")(
+        function* (tokenDigest) {
+          const outcome = yield* stub
+            .inspectRegistration(tokenDigest)
+            .pipe(Effect.mapError(clientUnavailable));
+
+          if ("_tag" in outcome) {
+            return yield* outcome;
+          }
+
+          return outcome;
+        },
+      ),
+      consumeRegistration: Effect.fn("AuthStoreObject.client.consumeRegistration")(
+        function* (input) {
+          const outcome = yield* stub
+            .consumeRegistration(input)
+            .pipe(Effect.mapError(clientUnavailable));
+
+          if (outcome !== null) {
+            return yield* outcome;
+          }
+        },
+      ),
+    });
+  }),
+);
+
+/**
+ * Everything the worker needs for a Durable-Object-backed `AuthStore`: the
+ * client layer wired to the given binding. The binding name is an intrinsic
+ * deployment definition, matching the `durable_objects` entry in the wrangler
+ * configuration.
+ */
+export const layerAuthStore = (options: {
+  readonly binding: string;
+}): Layer.Layer<
+  AuthStore,
+  Binding.BindingNotFoundError | Binding.BindingValidationError,
+  Environment.WorkerEnvironment
+> => layerAuthStoreClient.pipe(Layer.provide(AuthStoreObject.layer({ binding: options.binding })));
+
+// --- Email delivery ------------------------------------------------------------
+
+/** Send Email binding used by {@link layerEmailOtpSender}. */
+export class AuthEmail extends Email.Tag<AuthEmail>()("effect-auth/AuthEmail") {}
+
+/** Input handed to a {@link layerEmailOtpSender} content renderer. */
+export interface EmailOtpContentInput {
+  readonly code: string;
+  readonly minutesRemaining: number;
+}
+
+/** A rendered OTP message for {@link layerEmailOtpSender}. */
+export interface EmailOtpContent {
+  readonly subject: string;
+  readonly text: string;
+  /** HTML alternative to `text`; clients that render HTML prefer it. */
+  readonly html?: string;
+  /** Attachments, e.g. `cid:`-referenced inline images used by `html`. */
+  readonly attachments?: ReadonlyArray<Email.EmailAttachment>;
+}
+
+/**
+ * `EmailOtpSender` over a Cloudflare Send Email binding. The consumer owns the
+ * sending domain (Email Routing must be configured for `from`); message
+ * wording can be overridden through `content`.
+ *
+ * Delivery runs past the response via `waitUntil`: the provider call is the
+ * slow part of an OTP request (routinely multiple seconds), and by the time
+ * the sender runs the challenge is already persisted, so the endpoint's 202
+ * honestly means "accepted". The trade is that a failed send can no longer
+ * surface to the caller; the structured delivery-failure log is the only
+ * signal.
+ */
+export const layerEmailOtpSender = (options: {
+  /** `send_email` binding name from the wrangler configuration. */
+  readonly binding: string;
+  /**
+   * Verified sender address on a domain with Email Routing enabled. Pass an
+   * object to attach a display name.
+   */
+  readonly from: string | Email.EmailAddress;
+  readonly content?: (input: EmailOtpContentInput) => EmailOtpContent;
+}): Layer.Layer<
+  EmailOtpSender,
+  Binding.BindingNotFoundError | Binding.BindingValidationError,
+  Environment.WorkerEnvironment | Worker.WorkerContext
+> =>
+  Layer.effect(EmailOtpSender)(
+    Effect.gen(function* () {
+      const email = yield* AuthEmail;
+      const context = yield* Worker.WorkerContext;
+
+      return EmailOtpSender.of({
+        send: Effect.fn("EmailOtpSender.sendEmail")(function* (message) {
+          const now = yield* DateTime.now;
+
+          const minutesRemaining = Math.max(
+            1,
+            Math.round(
+              Duration.toMinutes(
+                Duration.millis(
+                  DateTime.toEpochMillis(message.expiresAt) - DateTime.toEpochMillis(now),
+                ),
+              ),
+            ),
+          );
+
+          const code = Redacted.value(message.code);
+
+          const rendered: EmailOtpContent = options.content?.({ code, minutesRemaining }) ?? {
+            subject: "Your sign-in code",
+            text: `Your sign-in code is ${code}. It expires in ${minutesRemaining} minute${
+              minutesRemaining === 1 ? "" : "s"
+            }. If you did not request it, ignore this email.`,
+          };
+
+          yield* context.waitUntil(
+            email
+              .send({
+                from: options.from,
+                to: message.email,
+                subject: rendered.subject,
+                text: rendered.text,
+                ...(rendered.html === undefined ? {} : { html: rendered.html }),
+                ...(rendered.attachments === undefined
+                  ? {}
+                  : { attachments: [...rendered.attachments] }),
+              })
+              .pipe(
+                Effect.asVoid,
+                // Delivery happens after the response, so this log is all an
+                // undeliverable address leaves behind. Provider reasons are
+                // operational and permanent — a suppressed recipient stays
+                // suppressed — so record enough to act on. Only the provider's
+                // own code and message are logged; the rendered message, which
+                // carries the code, never is.
+                Effect.tapError((error) =>
+                  Effect.logError("Sign-in code delivery failed", {
+                    code: Reflect.get(error, "code"),
+                    reason: String(Reflect.get(error, "cause") ?? error),
+                  }),
+                ),
+                // Logged above; a second generic waitUntil log adds nothing.
+                Effect.catch(() => Effect.void),
+              ),
+          );
+        }),
+      });
+    }),
+  ).pipe(Layer.provide(AuthEmail.layer({ binding: options.binding })));