@yielded/auth 0.1.0-beta.1

package/src/auth/Auth.ts

@@ -0,0 +1,482 @@
+import { Context, Effect, Exit, Layer, Option, Schema, Scope, type Types } from "effect";
+
+import { make as makeContract, type AnyAuthContract } from "../operations/actions";
+import type { AuthenticationAuthority } from "../sessions/AuthenticationAuthority";
+import {
+  configuredLayer,
+  type SessionConfiguration,
+  type SessionRequirements,
+} from "../sessions/configuration";
+import type { SessionConfigurationError } from "../sessions/errors";
+import { makeSessionModule, type ModuleService } from "../sessions/module";
+import { makeActionApi } from "./actions";
+import { AuthConfigurationError } from "./AuthConfigurationError";
+import { cryptoLayer, hooksLayer } from "./defaults";
+import type {
+  BoundSelection,
+  BoundStrategies,
+  BuiltStrategy as Strategy,
+  ClaimsCodec,
+  StrategySelection,
+} from "./definition";
+import { makeSessionApi } from "./session";
+
+type Strategies = Readonly<Record<string, Strategy>>;
+type CompletionOf<S> = S extends { readonly completion: infer C } ? C : false;
+
+const withConstructionLayer = <A, E, R, Provided, E2, R2>(
+  create: Effect.Effect<A, E, R>,
+  layer: Layer.Layer<Provided, E2, R2>,
+) =>
+  Effect.gen(function* () {
+    const current = yield* Effect.serviceOption(Layer.CurrentMemoMap);
+    const memoMap = Option.isSome(current) ? current.value : yield* Layer.makeMemoMap;
+    const scope = yield* Scope.fork(yield* Effect.scope);
+
+    return yield* Effect.gen(function* () {
+      const services = yield* Layer.buildWithMemoMap(layer, memoMap, scope);
+
+      return yield* create.pipe(
+        Effect.provide(services),
+        Scope.provide(scope),
+        Effect.provideService(Layer.CurrentMemoMap, memoMap),
+      );
+    }).pipe(Effect.onError((cause) => Scope.close(scope, Exit.failCause(cause))));
+  });
+
+type Api<S extends Strategy> = Effect.Success<S["make"]>;
+type StrategyMethod<S extends Strategy> = S extends Strategy ? Api<S>[keyof Api<S>] : never;
+type MethodNames<S extends Strategies> = S[keyof S] extends infer Strategy
+  ? Strategy extends { readonly make: Effect.Effect<infer Api, unknown, unknown> }
+    ? keyof Api
+    : never
+  : never;
+type Selected<S extends Strategies, M extends PropertyKey> = {
+  [K in keyof S]: M extends keyof Api<S[K]>
+    ? (strategy: K, input: Parameters<Api<S[K]>[M]>[0]) => ReturnType<Api<S[K]>[M]>
+    : never;
+}[keyof S];
+
+export type AuthApi<S extends Strategies, Default extends keyof S | undefined> = {
+  readonly [M in MethodNames<S>]: Types.UnionToIntersection<Selected<S, M>> &
+    (Default extends keyof S
+      ? M extends keyof Api<S[Default]>
+        ? Api<S[Default]>[M]
+        : unknown
+      : unknown);
+};
+
+type DefaultedName<Key extends string, Value extends string, Default extends string> = [
+  Value,
+  Default,
+] extends [Default, Value]
+  ? { readonly [K in Key]?: Value }
+  : { readonly [K in Key]: Value };
+
+type Names<Id extends string, SessionId extends string, Default extends string> = DefaultedName<
+  "namespace",
+  Id,
+  Default
+> &
+  DefaultedName<"sessionNamespace", SessionId, `${Id}/sessions`>;
+
+export type Options<
+  Claims extends ClaimsCodec,
+  S extends StrategySelection,
+  Default extends keyof S | undefined = undefined,
+  Id extends string = "effect-auth",
+  SessionId extends string = `${Id}/sessions`,
+  DefaultId extends string = "effect-auth",
+  Sessions extends SessionConfiguration | undefined = undefined,
+> = {
+  readonly claims: Claims;
+  readonly strategies?: S & Record<Exclude<keyof S, string>, never>;
+  /** Omit when supplying a custom SessionStrategy and completion through Layers. */
+  readonly sessions?: Sessions;
+  readonly defaultStrategy?: Default;
+} & Names<Id, SessionId, DefaultId>;
+
+const build = Effect.fn("Auth.make")(function* <
+  S extends Strategies,
+  Default extends keyof S | undefined,
+>(strategies: S, defaultStrategy: Default | undefined) {
+  type Build = S[keyof S]["make"];
+
+  const entries = Object.entries(strategies) as Array<
+    [
+      string,
+      {
+        readonly make: Effect.Effect<
+          Effect.Success<Build>,
+          Effect.Error<Build>,
+          Effect.Services<Build>
+        >;
+      },
+    ]
+  >;
+
+  const current = yield* Effect.serviceOption(Layer.CurrentMemoMap);
+  const memoMap = Option.isSome(current) ? current.value : yield* Layer.makeMemoMap;
+  const scope = yield* Scope.fork(yield* Effect.scope);
+
+  return yield* Effect.gen(function* () {
+    type Result = ReturnType<StrategyMethod<S[keyof S]>>;
+    type Callable = (
+      input: never,
+    ) => Effect.Effect<Effect.Success<Result>, Effect.Error<Result>, Effect.Services<Result>>;
+
+    const built = yield* Effect.forEach(entries, ([name, strategy]) =>
+      Effect.map(strategy.make, (api) => [name, api] as const),
+    );
+
+    const methodsByStrategy = new Map(
+      built as ReadonlyArray<readonly [string, Readonly<Record<string, Callable>>]>,
+    );
+
+    const names = new Set([...methodsByStrategy.values()].flatMap((api) => Object.keys(api)));
+
+    if (
+      ["then", "getSession", "requireSession", "verifySession", "signOut", "renewSession"].some(
+        (name) => names.has(name),
+      )
+    )
+      return yield* AuthConfigurationError.make({ reason: "method" });
+
+    const api = Object.fromEntries(
+      [...names].map((name) => [
+        name,
+        (...args: readonly unknown[]) =>
+          Effect.suspend(() => {
+            const selected = args.length === 2 ? args[0] : defaultStrategy;
+            const input = args.length === 2 ? args[1] : args[0];
+
+            const methods =
+              typeof selected === "string" ? methodsByStrategy.get(selected) : undefined;
+
+            if (args.length > 2 || methods === undefined || !Object.hasOwn(methods, name))
+              return Effect.die(AuthConfigurationError.make({ reason: "method" }));
+
+            return methods[name](input as never);
+          }),
+      ]),
+    );
+
+    // The dispatch table is assembled from these exact strategy/method pairs.
+    return {
+      api: Object.freeze(api) as AuthApi<S, Default>,
+      strategies: Object.freeze(Object.fromEntries(built)) as {
+        readonly [Name in keyof S]: Api<S[Name]>;
+      },
+    };
+  }).pipe(
+    Effect.provideService(Layer.CurrentMemoMap, memoMap),
+    Scope.provide(scope),
+    Effect.onError((cause) => Scope.close(scope, Exit.failCause(cause))),
+  );
+});
+
+const namespaceSchema = Schema.NonEmptyString.check(
+  Schema.isMaxLength(128),
+  Schema.isPattern(/^[A-Za-z0-9._:/-]+$/),
+);
+
+const strategyNameSchema = Schema.NonEmptyString.check(
+  Schema.isMaxLength(64),
+  Schema.isPattern(/^[A-Za-z0-9._-]+$/),
+);
+
+const configurationError = (
+  strategies: StrategySelection,
+  defaultStrategy: PropertyKey | undefined,
+  namespace: string,
+  sessionNamespace: string,
+) => {
+  if (!Schema.is(namespaceSchema)(namespace) || !Schema.is(namespaceSchema)(sessionNamespace))
+    return AuthConfigurationError.make({ reason: "namespace" });
+  const entries = Object.entries(strategies);
+
+  if (entries.some(([key]) => !Schema.is(strategyNameSchema)(key)))
+    return AuthConfigurationError.make({ reason: "strategies" });
+  if (defaultStrategy !== undefined && !Object.hasOwn(strategies, defaultStrategy))
+    return AuthConfigurationError.make({ reason: "default-strategy" });
+
+  const namespaces = entries.flatMap(([key, strategy]) =>
+    "bind" in strategy ? [strategy.namespace ?? `${namespace}/${key}`] : [],
+  );
+
+  if (namespaces.some((id) => !Schema.is(namespaceSchema)(id)))
+    return AuthConfigurationError.make({ reason: "namespace" });
+
+  return undefined;
+};
+
+/** Bind schemas and service keys once, before choosing the application's adapter Layers. */
+const bind = <
+  Claims extends ClaimsCodec,
+  const S extends StrategySelection = {},
+  const Default extends keyof S | undefined = undefined,
+  const Id extends string = "effect-auth",
+  const SessionId extends string = `${Id}/sessions`,
+  const Sessions extends SessionConfiguration | undefined = undefined,
+  Contract extends AnyAuthContract | undefined = undefined,
+>(
+  options: Options<Claims, S, Default, Id, SessionId, "effect-auth", Sessions>,
+  shared?: Contract,
+) => {
+  const strategies = { ...options.strategies };
+  const defaultStrategy = options.defaultStrategy;
+  // Defaults are fixed credential namespaces, never process-local random identities.
+  const namespace = (options.namespace ?? "effect-auth") as Id;
+  const sessionNamespace = (options.sessionNamespace ?? `${namespace}/sessions`) as SessionId;
+  const invalid = configurationError(strategies, defaultStrategy, namespace, sessionNamespace);
+
+  if (invalid !== undefined) throw invalid;
+  const sessions = makeSessionModule(sessionNamespace, options.claims);
+
+  const modules = Object.fromEntries(
+    Object.entries(strategies).map(([key, strategy]) => [
+      key,
+      "bind" in strategy
+        ? strategy.bind({
+            claims: options.claims,
+            namespace: strategy.namespace ?? `${namespace}/${key}`,
+            sessionNamespace,
+            sessions,
+          })
+        : { strategy },
+    ]),
+    // Each descriptor is bound to these exact claims, namespace and selection key.
+  ) as BoundStrategies<S, Claims, Id, SessionId>;
+
+  const selected = Object.fromEntries(
+    Object.entries(modules).map(([key, module]) => [key, module.strategy]),
+  ) as BoundSelection<typeof modules>;
+
+  type ContractDefinition = Contract extends AnyAuthContract
+    ? Contract
+    : ReturnType<typeof makeContract<Id, Claims>>;
+
+  const contract = (shared ??
+    makeContract(namespace, { claims: options.claims })) as ContractDefinition;
+
+  const create = Effect.gen(function* () {
+    const built = yield* build(selected, defaultStrategy);
+    const sessionApi = yield* makeSessionApi(sessions);
+
+    const raw = { ...built.api, ...sessionApi };
+
+    const actions = yield* makeActionApi<
+      typeof sessionApi,
+      typeof built.strategies,
+      Default,
+      ContractDefinition["actions"]
+    >(sessionApi, built.strategies, defaultStrategy, contract.actions);
+
+    return Object.freeze({ ...raw, ...actions }) as Omit<typeof raw, keyof typeof actions> &
+      typeof actions;
+  });
+
+  const completing = Object.values<Strategy>(selected).some(
+    (strategy) => strategy.completion === true,
+  );
+
+  const configured =
+    options.sessions === undefined
+      ? create
+      : !completing
+        ? withConstructionLayer(create, configuredLayer(sessions, options.sessions))
+        : withConstructionLayer(
+            create,
+            sessions
+              .completionLayer()
+              .pipe(
+                Layer.provideMerge(configuredLayer(sessions, options.sessions)),
+                Layer.provide([cryptoLayer, hooksLayer]),
+              ),
+          );
+
+  type SelectedStrategies = (typeof selected)[keyof typeof selected];
+  type Completes = true extends CompletionOf<SelectedStrategies> ? true : false;
+  type ConfigurationRequirements = Sessions extends SessionConfiguration
+    ?
+        | SessionRequirements<Sessions, SessionId, Claims>
+        | (Completes extends true ? AuthenticationAuthority : never)
+    : never;
+  type Provided = Sessions extends SessionConfiguration
+    ?
+        | ModuleService<SessionId, "strategy", Claims["Type"]>
+        | (Completes extends true ? ModuleService<SessionId, "completion", Claims["Type"]> : never)
+    : never;
+
+  // Runtime selection mirrors the session mode and presence of selected methods.
+  // Unconfigured definitions retain their explicit strategy/completion requirements.
+  const make = configured as Effect.Effect<
+    Effect.Success<typeof create>,
+    | Effect.Error<typeof create>
+    | (Sessions extends SessionConfiguration ? SessionConfigurationError : never),
+    Exclude<Effect.Services<typeof create>, Provided> | ConfigurationRequirements
+  >;
+
+  return Object.freeze({
+    claims: options.claims,
+    contract,
+    namespace,
+    sessions,
+    strategies: Object.freeze(modules),
+    make,
+  });
+};
+
+/** Identifier for a constant auth service. The stable name also isolates its credentials. */
+export interface AuthService<Id extends string, Claims> {
+  readonly id: Id;
+  readonly claims: Types.Invariant<Claims>;
+}
+
+const service =
+  <Self>() =>
+  <const Id extends string, A, E, R, Definition>(
+    id: Id,
+    definition: Definition,
+    create: Effect.Effect<A, E, R>,
+  ) => {
+    const Auth = Context.Service<Self, A>()(id);
+    const layer = Layer.effect(Auth, create);
+
+    return Object.assign(Auth, definition, { layer });
+  };
+
+/** Define one yieldable auth service, its schemas, extension ports and runtime Layer. */
+const makeService = <
+  const Id extends string,
+  Claims extends ClaimsCodec,
+  const S extends StrategySelection = {},
+  const Default extends keyof S | undefined = undefined,
+  const Namespace extends string = Id,
+  const SessionId extends string = `${Namespace}/sessions`,
+  const Sessions extends SessionConfiguration | undefined = undefined,
+  Contract extends AnyAuthContract | undefined = undefined,
+>(
+  id: Id,
+  options: Options<Claims, S, Default, Namespace, SessionId, Id, Sessions>,
+  contract?: Contract,
+) => {
+  if (!Schema.is(Schema.NonEmptyString)(id)) throw AuthConfigurationError.make({ reason: "id" });
+
+  const definition = bind<Claims, S, Default, Namespace, SessionId, Sessions, Contract>(
+    {
+      ...options,
+      namespace: options.namespace ?? id,
+    } as Options<Claims, S, Default, Namespace, SessionId, "effect-auth", Sessions>,
+    contract,
+  );
+
+  return service<AuthService<Id, Claims["Type"]>>()(id, definition, definition.make);
+};
+
+/** Create a yieldable auth service from a shared contract or service identifier.
+ * Use its Layer for provisioning, or yield its make Effect for direct construction.
+ * AuthRequest is resolved when a method executes. */
+export function make<
+  Contract extends AnyAuthContract,
+  const S extends StrategySelection = {},
+  const Default extends keyof S | undefined = undefined,
+  const Sessions extends SessionConfiguration | undefined = undefined,
+>(
+  contract: Contract,
+  options: Omit<
+    Options<
+      Contract["claims"],
+      S,
+      Default,
+      Contract["namespace"],
+      `${Contract["namespace"]}/sessions`,
+      Contract["namespace"],
+      Sessions
+    >,
+    "claims" | "namespace" | "sessionNamespace"
+  >,
+): ReturnType<
+  typeof makeService<
+    Contract["namespace"],
+    Contract["claims"],
+    S,
+    Default,
+    Contract["namespace"],
+    `${Contract["namespace"]}/sessions`,
+    Sessions,
+    Contract
+  >
+>;
+
+export function make<
+  const Id extends string,
+  Claims extends ClaimsCodec,
+  const S extends StrategySelection = {},
+  const Default extends keyof S | undefined = undefined,
+  const Namespace extends string = Id,
+  const SessionId extends string = `${Namespace}/sessions`,
+  const Sessions extends SessionConfiguration | undefined = undefined,
+>(
+  id: Id,
+  options: Options<Claims, S, Default, Namespace, SessionId, Id, Sessions>,
+): ReturnType<typeof makeService<Id, Claims, S, Default, Namespace, SessionId, Sessions>>;
+
+export function make(
+  definition: string | AnyAuthContract,
+  options: {
+    readonly claims?: ClaimsCodec;
+    readonly strategies?: StrategySelection;
+    readonly sessions?: SessionConfiguration;
+    readonly defaultStrategy?: string;
+    readonly namespace?: string;
+    readonly sessionNamespace?: string;
+  },
+): unknown {
+  if (typeof definition !== "string") {
+    return makeService(
+      definition.namespace,
+      {
+        ...options,
+        namespace: definition.namespace,
+        sessionNamespace: `${definition.namespace}/sessions`,
+        claims: definition.claims,
+      },
+      definition,
+    );
+  }
+  if (options.claims === undefined) throw AuthConfigurationError.make({ reason: "method" });
+  const namespace = options.namespace ?? definition;
+
+  return makeService(definition, {
+    ...options,
+    namespace,
+    sessionNamespace: options.sessionNamespace ?? `${namespace}/sessions`,
+    claims: options.claims,
+  });
+}
+
+/** Class form of the same auth definition, for applications using named service classes. */
+export const Service =
+  <Self>() =>
+  <
+    const Id extends string,
+    Claims extends ClaimsCodec,
+    const S extends StrategySelection = {},
+    const Default extends keyof S | undefined = undefined,
+    const Namespace extends string = Id,
+    const SessionId extends string = `${Namespace}/sessions`,
+    const Sessions extends SessionConfiguration | undefined = undefined,
+  >(
+    id: Id,
+    options: Options<Claims, S, Default, Namespace, SessionId, Id, Sessions>,
+  ) => {
+    if (!Schema.is(Schema.NonEmptyString)(id)) throw AuthConfigurationError.make({ reason: "id" });
+
+    const definition = bind<Claims, S, Default, Namespace, SessionId, Sessions>({
+      ...options,
+      namespace: options.namespace ?? id,
+    } as Options<Claims, S, Default, Namespace, SessionId, "effect-auth", Sessions>);
+
+    return service<Self>()(id, definition, definition.make);
+  };

package/src/auth/AuthConfigurationError.ts

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+
+/** Invalid auth composition, separate from an authentication failure. */
+export class AuthConfigurationError extends Schema.TaggedError<AuthConfigurationError>()(
+  "AuthConfigurationError",
+  {
+    reason: Schema.Literals(["id", "namespace", "strategies", "default-strategy", "method"]),
+  },
+) {}

package/src/auth/AuthRequest.ts

@@ -0,0 +1,21 @@
+import { Context, type Effect } from "effect";
+
+import type { HookDenied } from "../hooks/models";
+import type { AuthInvocation } from "../operations/context";
+import type { AuthResolvedCall } from "../operations/credentials";
+import type { SessionApiError } from "./session";
+
+/** Supplied by the host for one request or native workflow, never a shared auth Layer.
+ * @effect-leakable-service
+ */
+export class AuthRequest extends Context.Service<
+  AuthRequest,
+  AuthResolvedCall & {
+    /** Set by the trusted named action declaration while its implementation executes. */
+    readonly actionMode?: "query" | "mutation";
+    /** Host admission runs before mutation side effects; absent for trusted local callers. */
+    readonly beforeMutation?: Effect.Effect<void, HookDenied>;
+    /** HTTP adapters resolve caller authority only when an authentication method needs it. */
+    readonly resolveInvocation?: Effect.Effect<AuthInvocation, SessionApiError>;
+  }
+>()("effect-auth/AuthRequest") {}

package/src/auth/AuthStrategy.ts

@@ -0,0 +1,116 @@
+import { Context, Effect, Layer, Scope } from "effect";
+
+import type { AuthInvocation } from "../operations/context";
+import {
+  AuthCredentialCommandCollector,
+  AuthRevealCommandCollectorService,
+} from "../operations/credentials";
+import { AuthConfigurationError } from "./AuthConfigurationError";
+import { AuthRequest } from "./AuthRequest";
+import type { SessionApiError } from "./session";
+
+/** The same validated invocations used by local and transport callers. */
+export type AuthMethod = (
+  invocation: AuthInvocation,
+  input: never,
+) => Effect.Effect<unknown, unknown, unknown>;
+
+type RequestCollectorServices = AuthCredentialCommandCollector | AuthRevealCommandCollectorService;
+
+const unsupportedRevealCollector = Object.freeze({
+  supportedKinds: Object.freeze([]),
+  accept: () => Effect.void,
+});
+
+type BoundMethod<M extends AuthMethod, Provided> = (
+  ...args: [Parameters<M>[1]] extends [void]
+    ? [input?: Parameters<M>[1]]
+    : [input: Parameters<M>[1]]
+) => Effect.Effect<
+  Effect.Success<ReturnType<M>>,
+  Effect.Error<ReturnType<M>> | SessionApiError,
+  | AuthRequest
+  | Exclude<
+      Effect.Services<ReturnType<M>>,
+      Exclude<Provided | RequestCollectorServices, AuthRequest | Scope.Scope>
+    >
+>;
+
+/** Pair a selected, named API with its implementing Layer, preserving every method's types. */
+export const makeAuthStrategy = <
+  const Methods extends Readonly<Record<string, AuthMethod>>,
+  Provided,
+  E,
+  R,
+  const Completion extends boolean = false,
+>(
+  methods: Methods & { readonly then?: never } & Record<Exclude<keyof Methods, string>, never>,
+  layer: Layer.Layer<Provided, E, R>,
+  options?: { readonly completion: Completion },
+) => {
+  type Result = ReturnType<Methods[keyof Methods]>;
+
+  // A heterogeneous method table loses its key correlation during iteration.
+  const entries = Object.entries(methods) as Array<
+    [
+      string,
+      (
+        invocation: AuthInvocation,
+        input: never,
+      ) => Effect.Effect<Effect.Success<Result>, Effect.Error<Result>, Effect.Services<Result>>,
+    ]
+  >;
+
+  return Object.freeze({
+    completion: (options?.completion ?? false) as false | NoInfer<Completion>,
+    make: Effect.gen(function* () {
+      if (entries.some(([name]) => name === "then"))
+        return yield* AuthConfigurationError.make({ reason: "method" });
+
+      const built = yield* Layer.buildWithMemoMap(
+        layer,
+        yield* Layer.CurrentMemoMap,
+        yield* Effect.scope,
+      );
+
+      const services = Context.omit(
+        AuthRequest,
+        Scope.Scope,
+        AuthCredentialCommandCollector,
+        AuthRevealCommandCollectorService,
+      )(built);
+
+      const bound = Object.fromEntries(
+        entries.map(([name, invoke]) => [
+          name,
+          Effect.fn(`Auth.${name}`)(function* (input: never) {
+            // Resolve before providing the shared handler context: callers never get captured.
+            const request = yield* AuthRequest;
+
+            // Raw strategy methods are conservatively mutations. Only a trusted
+            // named query declaration can admit a read without mutation policy.
+            if (request.actionMode !== "query" && request.beforeMutation !== undefined)
+              yield* request.beforeMutation;
+
+            const invocation = yield* (
+              request.resolveInvocation ?? Effect.succeed(request.invocation)
+            );
+
+            const revealCollector = request.revealCommandCollector ?? unsupportedRevealCollector;
+
+            return yield* invoke(invocation, input).pipe(
+              Effect.provideService(AuthCredentialCommandCollector, request.credentialCommandSink),
+              Effect.provideService(AuthRevealCommandCollectorService, revealCollector),
+              Effect.provide(services),
+            );
+          }),
+        ]),
+      );
+
+      // Object.entries loses the key/signature correlation; each method above retains its invoke.
+      return Object.freeze(bound) as {
+        readonly [K in keyof Methods]: BoundMethod<Methods[K], Provided>;
+      };
+    }),
+  });
+};

package/src/auth/ConsumeDecision.ts

@@ -0,0 +1,4 @@
+/** Rejection stays a value until the physical owner commits its accounting. */
+export type ConsumeDecision<A> =
+  | { readonly _tag: "accepted"; readonly value: A }
+  | { readonly _tag: "rejected" };