@yielded/auth 0.1.0-beta.1

package/src/oauth/signInSnapshot.ts

@@ -0,0 +1,37 @@
+import { DateTime, Effect, Predicate, Schema } from "effect";
+
+import { OAuthUnavailable } from "./signInErrors";
+
+/** Private, bounded codecs only. Project before callbacks, then freeze the entire
+ * detached graph; never retain an application's mutable response object. */
+export const freezeOAuth = (value: unknown): void => {
+  if (!Predicate.isObjectOrArray(value) || Object.isFrozen(value)) return;
+  if (DateTime.isDateTime(value)) Object.freeze(DateTime.toPartsUtc(value));
+  for (const child of Object.values(value)) freezeOAuth(child);
+  Object.freeze(value);
+};
+
+export const snapshotOAuthSync = <S extends Schema.Codec<unknown, unknown, never, never>>(
+  schema: S,
+  value: S["Type"],
+): S["Type"] => {
+  try {
+    const codec = Schema.toCodecJson(Schema.toType(schema));
+    const result = Schema.decodeSync(codec)(Schema.encodeSync(codec)(value));
+
+    freezeOAuth(result);
+
+    return result;
+  } catch {
+    throw OAuthUnavailable.make({});
+  }
+};
+
+export const snapshotOAuth = <S extends Schema.Codec<unknown, unknown, never, never>>(
+  schema: S,
+  value: S["Type"],
+) =>
+  Effect.try({
+    try: () => snapshotOAuthSync(schema, value),
+    catch: () => OAuthUnavailable.make({}),
+  });

package/src/oauth/transactionEncryption.ts

@@ -0,0 +1,198 @@
+// oxlint-disable-next-line import/extensions -- Noble exposes only its explicit .js subpath.
+import { xchacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { Crypto, Effect, Encoding, Redacted, Result, Schema } from "effect";
+
+import { OAuthConfigurationError, OAuthUnavailable } from "./signInErrors";
+import {
+  OAuthEncryptionKeyId,
+  OAuthSealedTransaction,
+  OAuthTransactionSecrets,
+} from "./signInModels";
+import { snapshotOAuthSync } from "./signInSnapshot";
+
+export interface OAuthTransactionKeyring {
+  readonly activeKeyId: string;
+  readonly keys: ReadonlyArray<{
+    readonly id: string;
+    readonly material: Redacted.Redacted<string>;
+  }>;
+}
+
+const keyringSchema = Schema.Struct({
+  activeKeyId: OAuthEncryptionKeyId,
+  keys: Schema.Array(
+    Schema.Struct({
+      id: OAuthEncryptionKeyId,
+      material: Schema.Redacted(Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_-]{43}$/))),
+    }),
+  ).check(Schema.isMinLength(1), Schema.isMaxLength(8)),
+});
+
+const encoder = new TextEncoder();
+const secretCodec = Schema.fromJsonString(OAuthTransactionSecrets);
+
+const decodeBase64 = (value: string, maximum: number, exact?: number) => {
+  if (
+    value.length > Math.ceil((maximum * 4) / 3) ||
+    value.length % 4 === 1 ||
+    !/^[A-Za-z0-9_-]+$/.test(value)
+  ) {
+    throw OAuthUnavailable.make({});
+  }
+  const bytes = Result.getOrUndefined(Encoding.decodeBase64Url(value));
+
+  if (
+    !bytes ||
+    bytes.length > maximum ||
+    (exact !== undefined && bytes.length !== exact) ||
+    Encoding.encodeBase64Url(bytes) !== value
+  ) {
+    bytes?.fill(0);
+    throw OAuthUnavailable.make({});
+  }
+
+  return bytes;
+};
+
+const validateSecrets = (
+  context: { readonly protocol: "oidc" | "oauth" },
+  secrets: OAuthTransactionSecrets,
+) => {
+  const value = snapshotOAuthSync(OAuthTransactionSecrets, secrets);
+
+  if ((context.protocol === "oidc") !== (value.oidcNonce !== undefined))
+    throw OAuthUnavailable.make({});
+  for (const raw of [value.state, value.oidcNonce]) {
+    if (raw !== undefined) decodeBase64(Redacted.value(raw), 32, 32).fill(0);
+  }
+
+  return value;
+};
+
+/** Private primitive: public protectors each own a fixed typed AAD domain. */
+export const transactionEncryption = <C extends { readonly protocol: "oidc" | "oauth" }>(
+  contextSchema: Schema.Codec<C, unknown, never, never>,
+  aad: (context: C, keyId: string) => Uint8Array,
+  keyring: OAuthTransactionKeyring,
+) => {
+  let captured: typeof keyringSchema.Type | undefined;
+
+  try {
+    captured = snapshotOAuthSync(keyringSchema, keyring);
+  } catch {
+    /* validated by Layer */
+  }
+
+  return Effect.gen(function* () {
+    if (captured === undefined) return yield* OAuthConfigurationError.make({ reason: "keyring" });
+    const configuration = captured;
+    const crypto = yield* Crypto.Crypto;
+    const randomBytes = crypto.randomBytes;
+
+    const keys = yield* Effect.try({
+      try: () => {
+        const map = new Map<string, Uint8Array>();
+
+        try {
+          for (const entry of configuration.keys) {
+            if (map.has(entry.id)) throw OAuthUnavailable.make({});
+            map.set(entry.id, decodeBase64(Redacted.value(entry.material), 32, 32));
+          }
+          if (!map.has(configuration.activeKeyId)) throw OAuthUnavailable.make({});
+
+          return map;
+        } catch (error) {
+          for (const key of map.values()) key.fill(0);
+          throw error;
+        }
+      },
+      catch: () => OAuthConfigurationError.make({ reason: "keyring" }),
+    });
+
+    return {
+      seal: Effect.fn("OAuthTransactionProtector.seal")(function* (input: {
+        readonly context: C;
+        readonly secrets: OAuthTransactionSecrets;
+      }) {
+        const retained = yield* Effect.try({
+          try: () => ({
+            context: snapshotOAuthSync(contextSchema, input.context),
+            secrets: validateSecrets(input.context, input.secrets),
+          }),
+          catch: () => OAuthUnavailable.make({}),
+        });
+
+        const nonce = yield* randomBytes(24).pipe(Effect.mapError(() => OAuthUnavailable.make({})));
+
+        return yield* Effect.try({
+          try: () => {
+            let plaintext: Uint8Array | undefined;
+            let ciphertext: Uint8Array | undefined;
+            let associated: Uint8Array | undefined;
+
+            try {
+              plaintext = encoder.encode(Schema.encodeSync(secretCodec)(retained.secrets));
+              associated = aad(retained.context, configuration.activeKeyId);
+              if (plaintext.length > 16384 || nonce.length !== 24) throw OAuthUnavailable.make({});
+              ciphertext = xchacha20poly1305(
+                keys.get(configuration.activeKeyId)!,
+                nonce,
+                associated,
+              ).encrypt(plaintext);
+
+              return snapshotOAuthSync(OAuthSealedTransaction, {
+                format: "oauth-xchacha20poly1305-v1",
+                keyId: configuration.activeKeyId,
+                nonce: Encoding.encodeBase64Url(nonce),
+                ciphertext: Redacted.make(Encoding.encodeBase64Url(ciphertext)),
+              });
+            } finally {
+              plaintext?.fill(0);
+              ciphertext?.fill(0);
+              associated?.fill(0);
+              nonce.fill(0);
+            }
+          },
+          catch: () => OAuthUnavailable.make({}),
+        });
+      }),
+      open: Effect.fn("OAuthTransactionProtector.open")(
+        (input: { readonly context: C; readonly sealed: OAuthSealedTransaction }) =>
+          Effect.try({
+            try: () => {
+              const context = snapshotOAuthSync(contextSchema, input.context);
+              const sealed = snapshotOAuthSync(OAuthSealedTransaction, input.sealed);
+              const key = keys.get(sealed.keyId);
+
+              if (!key) throw OAuthUnavailable.make({});
+              let nonce: Uint8Array | undefined;
+              let ciphertext: Uint8Array | undefined;
+              let associated: Uint8Array | undefined;
+              let plaintext: Uint8Array | undefined;
+
+              try {
+                nonce = decodeBase64(sealed.nonce, 24, 24);
+                ciphertext = decodeBase64(Redacted.value(sealed.ciphertext), 16400);
+                associated = aad(context, sealed.keyId);
+                plaintext = xchacha20poly1305(key, nonce, associated).decrypt(ciphertext);
+                if (plaintext.length > 16384) throw OAuthUnavailable.make({});
+                const json = new TextDecoder("utf-8", { fatal: true }).decode(plaintext);
+                const secrets = Schema.decodeSync(secretCodec)(json);
+
+                if (Schema.encodeSync(secretCodec)(secrets) !== json)
+                  throw OAuthUnavailable.make({});
+
+                return validateSecrets(context, secrets);
+              } finally {
+                nonce?.fill(0);
+                ciphertext?.fill(0);
+                associated?.fill(0);
+                plaintext?.fill(0);
+              }
+            },
+            catch: () => OAuthUnavailable.make({}),
+          }),
+      ),
+    };
+  });
+};

package/src/operations/RequestBindingConfig.ts

@@ -0,0 +1,12 @@
+import { Context, Layer } from "effect";
+
+import type { RequestBindingConfiguration } from "./requestBinding";
+
+/** Dedicated request-binding keys, shared by the selected authentication methods. */
+export class RequestBindingConfig extends Context.Service<
+  RequestBindingConfig,
+  RequestBindingConfiguration
+>()("effect-auth/RequestBindingConfig") {
+  static readonly layer = (configuration: RequestBindingConfiguration) =>
+    Layer.succeed(this, configuration);
+}

package/src/operations/actions.ts

@@ -0,0 +1,342 @@
+import type { Effect } from "effect";
+import { Schema, SchemaAST } from "effect";
+import type { Rpc } from "effect/unstable/rpc";
+
+import { HookDenied } from "../hooks/models";
+import { makeSessionContract } from "../sessions/contract";
+import { SessionError, SessionSignOutUnavailable } from "../sessions/errors";
+import { SessionSignOut } from "../sessions/models";
+import type { AuthInvocation } from "./context";
+import type { CredentialSlot } from "./credentials";
+import { OperationConfigurationError } from "./errors";
+import { makeOperation, type OperationReplay } from "./operation";
+import type { AuthRevealKind } from "./reveals";
+
+/** Public action data is shared by local, HTTP and reactive callers. Private
+ * request fields are supplied by the server when the implementation executes. */
+export interface ActionOptions<
+  Payload extends Schema.Top,
+  Success extends Schema.Top,
+  Failure extends Schema.Top,
+  Mode extends "query" | "mutation" = "query" | "mutation",
+> {
+  readonly payload: Payload;
+  readonly success: Success;
+  readonly error: Failure;
+  readonly mode: Mode;
+  readonly replay?: OperationReplay;
+  readonly credentials?: boolean;
+  readonly reveals?: ReadonlyArray<AuthRevealKind>;
+  readonly method?: string;
+  readonly strategy?: string;
+  readonly requestFields?: Readonly<Record<string, CredentialSlot>>;
+  readonly subject?: {
+    fromSuccess(value: Success["Type"]): string | null | undefined;
+  };
+}
+
+/** Define the schema and behavior of one public method, independently of its
+ * implementation. Inputs use the schema's encoded form, matching operation.invoke. */
+export const action = <
+  Payload extends Schema.Top,
+  Success extends Schema.Top,
+  Failure extends Schema.Top,
+  const Mode extends "query" | "mutation",
+  const Method extends string | undefined = undefined,
+  const Strategy extends string | undefined = undefined,
+>(
+  options: ActionOptions<Payload, Success, Failure, Mode> & {
+    readonly method?: Method;
+    readonly strategy?: Strategy;
+  },
+) =>
+  Object.freeze({
+    ...options,
+    method: options.method,
+    strategy: options.strategy,
+    requestFields: Object.freeze({ ...options.requestFields }),
+    reveals: Object.freeze([...(options.reveals ?? [])]),
+  });
+
+export type ActionDefinition = ActionOptions<Schema.Top, Schema.Top, Schema.Top>;
+export type ActionDefinitions = Readonly<Record<string, ActionDefinition>>;
+
+/** Reuse a pure operation contract for a named action. Request credential fields
+ * are removed from the public schema and restored only by the local request adapter. */
+export const fromOperation = <
+  Fields extends Schema.Struct.Fields,
+  Success extends Schema.Top,
+  Failure extends Schema.Top,
+  const RequestFields extends Readonly<Record<string, CredentialSlot>> = Record<never, never>,
+  const Mode extends "query" | "mutation" = "mutation",
+  const Method extends string | undefined = undefined,
+  const Strategy extends string | undefined = undefined,
+>(
+  operation: {
+    readonly rpc: {
+      readonly payloadSchema: Schema.Struct<Fields>;
+      readonly successSchema: Success;
+      readonly errorSchema: Failure;
+    };
+    readonly exposure: "public" | "internal";
+    readonly replay: OperationReplay;
+    readonly credentials: boolean;
+    readonly reveals: ReadonlyArray<AuthRevealKind>;
+  },
+  options: {
+    readonly method?: Method;
+    readonly strategy?: Strategy;
+    readonly requestFields?: RequestFields &
+      Record<Exclude<keyof RequestFields, Extract<keyof Fields, string>>, never>;
+    readonly mode?: Mode;
+    readonly subject?: { fromSuccess(value: Success["Type"]): string | null | undefined };
+  } = {},
+) => {
+  if (operation.exposure !== "public")
+    throw OperationConfigurationError.make({
+      reason: "internal-exposure",
+      operation: options.method ?? "action",
+    });
+
+  // Schema fields and their keys remain paired while removing request-only input.
+  const fields = Object.fromEntries(
+    Object.entries(operation.rpc.payloadSchema.fields).filter(
+      ([name]) => !Object.hasOwn(options.requestFields ?? {}, name),
+    ),
+  ) as Omit<Fields, keyof RequestFields>;
+
+  return action({
+    payload: Schema.Struct(fields),
+    success: operation.rpc.successSchema,
+    error: operation.rpc.errorSchema,
+    replay: operation.replay,
+    credentials: operation.credentials,
+    reveals: operation.reveals,
+    ...options,
+    mode: (options.mode ?? "mutation") as Mode,
+  });
+};
+
+const bindAction = <
+  const Name extends string,
+  Payload extends Schema.Top,
+  Success extends Schema.Top,
+  Failure extends Schema.Top,
+  Mode extends "query" | "mutation",
+>(
+  namespace: string,
+  basePath: `/${string}`,
+  name: Name,
+  definition: ActionOptions<Payload, Success, Failure, Mode>,
+) => {
+  const requestFields = Object.freeze({ ...definition.requestFields });
+  const reveals = Object.freeze([...(definition.reveals ?? [])]);
+
+  if (
+    !Schema.is(Schema.NonEmptyString.check(Schema.isPattern(/^[A-Za-z][A-Za-z0-9]*$/)))(name) ||
+    [
+      "then",
+      "__proto__",
+      "constructor",
+      "prototype",
+      "session",
+      "lifetime",
+      "runtime",
+      "client",
+    ].includes(name) ||
+    (definition.mode === "query" &&
+      (definition.credentials === true ||
+        reveals.length > 0 ||
+        (definition.replay !== undefined && definition.replay !== "read-only")))
+  )
+    throw OperationConfigurationError.make({ reason: "invalid-action", operation: name });
+
+  const operation = makeOperation(`${namespace}/api/${name}`, {
+    payload: definition.payload,
+    success: definition.success,
+    error: Schema.Union([definition.error, SessionError, HookDenied]),
+    access: "any",
+    exposure: "public",
+    replay: definition.mode === "query" ? "read-only" : (definition.replay ?? "non-idempotent"),
+    ...(definition.credentials === true ? { credentials: true as const } : {}),
+    ...(reveals.length > 0 ? { reveals } : {}),
+  });
+
+  return Object.freeze({
+    route: Object.freeze({
+      operation,
+      path: `${basePath}/${name}` as const,
+      method:
+        definition.mode === "query" &&
+        Object.keys(requestFields).length === 0 &&
+        (SchemaAST.isVoid(Schema.toEncoded(definition.payload).ast) ||
+          SchemaAST.isUndefined(Schema.toEncoded(definition.payload).ast))
+          ? ("GET" as const)
+          : ("POST" as const),
+      credentials: Object.freeze({}),
+      reveals,
+    }),
+    mode: definition.mode,
+    method: definition.method ?? name,
+    strategy: definition.strategy,
+    requestFields,
+    subject: definition.subject,
+  });
+};
+
+export interface AnyAuthAction {
+  readonly route: {
+    readonly operation: {
+      readonly rpc: Rpc.AnyWithProps;
+      readonly exposure: "public" | "internal";
+      readonly replay: OperationReplay;
+      readonly credentials: boolean;
+      readonly reveals: ReadonlyArray<AuthRevealKind>;
+      readonly invokeUnknown: (
+        invocation: AuthInvocation,
+        input: unknown,
+      ) => Effect.Effect<unknown, unknown, unknown>;
+    };
+    readonly path: `/${string}`;
+    readonly method: "POST" | "GET";
+    readonly credentials: Readonly<Record<never, never>>;
+    readonly reveals: ReadonlyArray<AuthRevealKind>;
+  };
+  readonly mode: "query" | "mutation";
+  readonly method: string;
+  readonly strategy: string | undefined;
+  readonly requestFields: Readonly<Record<string, CredentialSlot>>;
+  readonly subject?: { fromSuccess(value: unknown): string | null | undefined } | undefined;
+}
+
+export type AuthActions = Readonly<Record<string, AnyAuthAction>>;
+
+type Target<Definition, Key extends "method" | "strategy", Default> = Key extends keyof Definition
+  ? Exclude<Definition[Key], undefined> | (undefined extends Definition[Key] ? Default : never)
+  : Default;
+
+export type BoundActions<Definitions extends ActionDefinitions> = {
+  readonly [Name in keyof Definitions]: Definitions[Name] extends ActionOptions<
+    infer P,
+    infer S,
+    infer E,
+    infer M
+  >
+    ? Omit<
+        ReturnType<typeof bindAction<Extract<Name, string>, P, S, E, M>>,
+        "method" | "strategy"
+      > & {
+        readonly method: Target<Definitions[Name], "method", Extract<Name, string>>;
+        readonly strategy: Target<Definitions[Name], "strategy", undefined>;
+      }
+    : never;
+};
+
+const sessionActions = <
+  S extends Schema.Codec<{ readonly subjectId: string }, unknown, unknown, unknown>,
+>(
+  session: S,
+) => ({
+  getSession: action({
+    payload: Schema.Void,
+    success: Schema.NullOr(session),
+    error: Schema.Never,
+    mode: "query",
+    subject: { fromSuccess: (value) => value?.subjectId ?? null },
+  }),
+  requireSession: action({
+    payload: Schema.Void,
+    success: session,
+    error: Schema.Never,
+    mode: "query",
+    subject: { fromSuccess: (value) => value.subjectId },
+  }),
+  signOut: action({
+    payload: Schema.Void,
+    success: Schema.Union([SessionSignOut, SessionSignOutUnavailable]),
+    error: Schema.Never,
+    mode: "mutation",
+    replay: "idempotent",
+    credentials: true,
+    subject: { fromSuccess: () => null },
+  }),
+  renewSession: action({
+    payload: Schema.Void,
+    success: session,
+    error: Schema.Never,
+    mode: "mutation",
+    credentials: true,
+  }),
+});
+
+/** A browser-safe contract. The action callback only receives schemas; it never
+ * receives server configuration, keys, persistence or service implementations. */
+export const make = <
+  const Id extends string,
+  Claims extends Schema.Codec<unknown, unknown, unknown, unknown>,
+  const Additional extends ActionDefinitions = {},
+>(
+  namespace: Id,
+  options: {
+    readonly claims: Claims;
+    readonly basePath?: `/${string}`;
+    readonly actions?: (
+      schemas: ReturnType<typeof makeSessionContract<`${Id}/sessions`, Claims>>,
+    ) => Additional;
+  },
+) => {
+  if (
+    !Schema.is(
+      Schema.NonEmptyString.check(Schema.isMaxLength(128), Schema.isPattern(/^[A-Za-z0-9._:/-]+$/)),
+    )(namespace)
+  )
+    throw OperationConfigurationError.make({ reason: "invalid-action", operation: namespace });
+
+  const basePath = options.basePath ?? "/auth";
+
+  if (
+    !Schema.is(Schema.String.check(Schema.isPattern(/^\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+$/)))(
+      basePath,
+    )
+  )
+    throw OperationConfigurationError.make({ reason: "invalid-action", operation: namespace });
+
+  const sessions = makeSessionContract(`${namespace}/sessions`, options.claims);
+  const defaults = sessionActions(sessions.Session);
+  const additional = options.actions?.(sessions) ?? {};
+
+  if (Object.keys(additional).some((name) => Object.hasOwn(defaults, name)))
+    throw OperationConfigurationError.make({ reason: "duplicate-operation", operation: namespace });
+
+  const definitions = { ...defaults, ...additional };
+
+  const actions = Object.fromEntries(
+    (Object.entries(definitions) as Array<[string, ActionDefinition]>).map(([name, definition]) => [
+      name,
+      bindAction(namespace, basePath, name, definition),
+    ]),
+  );
+
+  // Each entry is bound with the exact schemas from the corresponding definition.
+  return Object.freeze({
+    namespace,
+    claims: options.claims,
+    sessions,
+    actions: Object.freeze(actions) as unknown as BoundActions<typeof defaults & Additional>,
+  });
+};
+
+export interface AnyAuthContract {
+  readonly namespace: string;
+  readonly claims: Schema.Codec<unknown, unknown, unknown, unknown>;
+  readonly actions: AuthActions;
+}
+
+export type ActionInput<A extends AnyAuthAction> =
+  A["route"]["operation"]["rpc"]["payloadSchema"]["Encoded"];
+
+export type ActionSuccess<A extends AnyAuthAction> =
+  A["route"]["operation"]["rpc"]["successSchema"]["Type"];
+
+export type ActionError<A extends AnyAuthAction> =
+  A["route"]["operation"]["rpc"]["errorSchema"]["Type"];