@dual-os/sdk 0.0.0-stage → 0.8.0-next.0

package/src/AuthMethod.ts

@@ -0,0 +1,954 @@
+/**
+ * Canonical auth-method definition builders and types for the Dual SDK.
+ *
+ * Providers own auth methods shared by all actions and triggers under them.
+ *
+ * @since 0.0.0
+ */
+import { Function as Func, Predicate, Schema } from "effect";
+import type { Config, Effect, Pipeable } from "effect";
+
+import type * as Types from "effect/Types";
+
+import { validateIdentifier } from "./internal/identifier.ts";
+import { PipeableProto } from "./internal/proto.ts";
+import type * as OAuth2TokenRefresher from "./OAuth2TokenRefresher.ts";
+
+/**
+ * @since 0.0.0
+ * @category type ids
+ */
+export const TypeId = "@dual-os/sdk/AuthMethod" as const;
+
+/**
+ * @since 0.0.0
+ * @category type ids
+ */
+export type TypeId = typeof TypeId;
+
+/**
+ * Phantom inference slot for the hook requirements union.
+ *
+ * Unlike the schema parameters, hook requirements only occur inside optional
+ * hook signatures, which TypeScript cannot reliably infer through; this slot
+ * gives the {@link Requirements} extractor a stable inference site.
+ *
+ * One union instead of per-hook parameters on purpose: in practice a method's
+ * dependencies are provided once at the plugin/app definition (for example a
+ * Gmail client layer), not separately per hook, and every consumption path
+ * (invoke, trigger phases, credential lifecycle, `DualRuntime.toLayer`) must demand
+ * the same set so none of them can silently under-require.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface RequirementsVariance<out Requirements> {
+  readonly _Requirements: Types.Covariant<Requirements>;
+}
+
+/**
+ * Constraint type for working with any {@link AuthMethod}.
+ *
+ * @since 0.0.0
+ * @category type-level
+ */
+export interface Any extends Pipeable.Pipeable {
+  readonly [TypeId]: RequirementsVariance<any>;
+  readonly identifier: string;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly kind: AuthMethodKind;
+  readonly setup: Schema.Top | undefined;
+  readonly input: Schema.Top | undefined;
+  readonly material: Schema.Top;
+  readonly value: Schema.Top;
+  readonly schema: Schema.Top;
+  readonly prepare: unknown;
+  readonly refresh: unknown;
+  readonly resolve: unknown;
+  readonly display: unknown;
+  readonly test: unknown;
+  readonly oauth2: OAuth2Setup<Schema.Top, any, any> | undefined;
+}
+
+/** @since 0.0.0 @category models */
+export type AuthMethodKind = "form" | "oauth2" | "custom";
+
+/** @since 0.0.0 @category type-level */
+export type SchemaType<SchemaDef extends Schema.Top | undefined> = SchemaDef extends Schema.Top
+  ? Schema.Schema.Type<SchemaDef>
+  : undefined;
+
+/** @since 0.0.0 @category hooks */
+export interface HookContext<Setup = undefined> {
+  readonly setup: Setup;
+}
+
+/** @since 0.0.0 @category hooks */
+export type MaybeEffect<Value, Error = never, Requirements = never> =
+  | Value
+  | Effect.Effect<Value, Error, Requirements>;
+
+/** @since 0.0.0 @category hooks */
+export type PrepareHook<Input, Material, Error = never, Requirements = never, Setup = undefined> = (
+  input: Input,
+  context: HookContext<Setup>,
+) => MaybeEffect<Material, Error, Requirements>;
+
+/** @since 0.0.0 @category hooks */
+export type RefreshReason = "before-use" | "forced";
+
+/** @since 0.0.0 @category hooks */
+export interface RefreshContext<Setup = undefined> extends HookContext<Setup> {
+  readonly now: number;
+  readonly minValidityMs: number;
+  readonly reason: RefreshReason;
+}
+
+/** @since 0.0.0 @category hooks */
+export type RefreshHook<Material, Error = never, Requirements = never, Setup = undefined> = (
+  material: Material,
+  context: RefreshContext<Setup>,
+) => MaybeEffect<Material | undefined, Error, Requirements>;
+
+/** @since 0.0.0 @category hooks */
+export type ResolveHook<Material, Value, Error = never, Requirements = never, Setup = undefined> = (
+  material: Material,
+  context: HookContext<Setup>,
+) => MaybeEffect<Value, Error, Requirements>;
+
+/** @since 0.0.0 @category models */
+export interface Display {
+  readonly label?: string;
+  readonly description?: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+/** @since 0.0.0 @category hooks */
+export type DisplayHook<Material, Error = never, Requirements = never, Setup = undefined> = (
+  material: Material,
+  context: HookContext<Setup>,
+) => MaybeEffect<Display, Error, Requirements>;
+
+/** @since 0.0.0 @category models */
+export interface TestResult {
+  readonly ok: boolean;
+  readonly message?: string;
+}
+
+/** @since 0.0.0 @category errors */
+export class ExpectedOAuth2MethodError extends Schema.TaggedError<ExpectedOAuth2MethodError>()(
+  "ExpectedOAuth2MethodError",
+  { methodIdentifier: Schema.String },
+) {}
+
+/** @since 0.0.0 @category hooks */
+export type TestHook<Material, Error = never, Requirements = never, Setup = undefined> = (
+  material: Material,
+  context: HookContext<Setup>,
+) => MaybeEffect<TestResult, Error, Requirements>;
+
+/**
+ * Options used to create an {@link AuthMethod}.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface AuthMethodOptions<ValueSchema extends Schema.Top> {
+  readonly name?: string;
+  readonly description?: string;
+  readonly schema: ValueSchema;
+}
+
+/** @since 0.0.0 @category models */
+export interface FormOptions<
+  ValueSchema extends Schema.Top,
+  SetupSchema extends Schema.Top | undefined = undefined,
+> extends AuthMethodOptions<ValueSchema> {
+  readonly setup?: SetupSchema;
+}
+
+/** @since 0.0.0 @category models */
+export interface AuthOptionsWithoutMaterial<
+  InputSchema extends Schema.Top,
+  ValueSchema extends Schema.Top = InputSchema,
+  SetupSchema extends Schema.Top | undefined = undefined,
+  PrepareRequirements = never,
+  RefreshRequirements = never,
+  ResolveRequirements = never,
+  DisplayRequirements = never,
+  TestRequirements = never,
+> {
+  readonly name?: string;
+  readonly description?: string;
+  readonly setup?: SetupSchema;
+  readonly input: InputSchema;
+  readonly material?: undefined;
+  readonly value?: ValueSchema;
+  readonly prepare?: PrepareHook<
+    SchemaType<InputSchema>,
+    SchemaType<InputSchema>,
+    any,
+    PrepareRequirements,
+    SchemaType<SetupSchema>
+  >;
+  readonly refresh?: RefreshHook<
+    SchemaType<InputSchema>,
+    any,
+    RefreshRequirements,
+    SchemaType<SetupSchema>
+  >;
+  readonly resolve?: ResolveHook<
+    SchemaType<InputSchema>,
+    Schema.Schema.Type<ValueSchema>,
+    any,
+    ResolveRequirements,
+    SchemaType<SetupSchema>
+  >;
+  readonly display?: DisplayHook<
+    SchemaType<InputSchema>,
+    any,
+    DisplayRequirements,
+    SchemaType<SetupSchema>
+  >;
+  readonly test?: TestHook<SchemaType<InputSchema>, any, TestRequirements, SchemaType<SetupSchema>>;
+}
+
+/** @since 0.0.0 @category models */
+export interface AuthOptionsWithMaterial<
+  InputSchema extends Schema.Top | undefined,
+  MaterialSchema extends Schema.Top,
+  ValueSchema extends Schema.Top = MaterialSchema,
+  SetupSchema extends Schema.Top | undefined = undefined,
+  PrepareRequirements = never,
+  RefreshRequirements = never,
+  ResolveRequirements = never,
+  DisplayRequirements = never,
+  TestRequirements = never,
+> {
+  readonly name?: string;
+  readonly description?: string;
+  readonly setup?: SetupSchema;
+  readonly input: InputSchema;
+  readonly material: MaterialSchema;
+  readonly value?: ValueSchema;
+  readonly prepare?: PrepareHook<
+    SchemaType<InputSchema>,
+    Schema.Schema.Type<MaterialSchema>,
+    any,
+    PrepareRequirements,
+    SchemaType<SetupSchema>
+  >;
+  readonly refresh?: RefreshHook<
+    Schema.Schema.Type<MaterialSchema>,
+    any,
+    RefreshRequirements,
+    SchemaType<SetupSchema>
+  >;
+  readonly resolve?: ResolveHook<
+    Schema.Schema.Type<MaterialSchema>,
+    Schema.Schema.Type<ValueSchema>,
+    any,
+    ResolveRequirements,
+    SchemaType<SetupSchema>
+  >;
+  readonly display?: DisplayHook<
+    Schema.Schema.Type<MaterialSchema>,
+    any,
+    DisplayRequirements,
+    SchemaType<SetupSchema>
+  >;
+  readonly test?: TestHook<
+    Schema.Schema.Type<MaterialSchema>,
+    any,
+    TestRequirements,
+    SchemaType<SetupSchema>
+  >;
+}
+
+/** @since 0.0.0 @category models */
+export interface OAuth2ClientConfig {
+  readonly clientId: string | Config.Config<string>;
+  readonly clientSecret?: string | Config.Config<string>;
+  readonly authentication?: "basic" | "post" | "none";
+}
+
+/** @since 0.0.0 @category hooks */
+export type OAuth2ClientHook<Setup> = (context: HookContext<Setup>) => OAuth2ClientConfig;
+
+/** @since 0.0.0 @category models */
+export type OAuth2Client<Setup = undefined> = OAuth2ClientConfig | OAuth2ClientHook<Setup>;
+
+/** @since 0.0.0 @category hooks */
+export type OAuth2EndpointHook<Setup> = (context: HookContext<Setup>) => string;
+
+/**
+ * An OAuth2 endpoint, fixed or derived from the setup.
+ *
+ * Providers that host one instance per customer — a Microsoft tenant, a
+ * self-hosted GitLab — cannot name their endpoints until the connection's setup
+ * says which instance it is.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export type OAuth2Endpoint<Setup = undefined> = string | OAuth2EndpointHook<Setup>;
+
+/** @since 0.0.0 @category models */
+export type OAuth2ParamsHook<Setup> = (
+  context: HookContext<Setup>,
+) => Readonly<Record<string, string>>;
+
+/**
+ * Query parameters added to the authorization or token request, fixed or
+ * derived from the setup — the same freedom the endpoints have. A provider
+ * that knows which account a connection is for can say so in the request
+ * instead of leaving the choice to whatever session the browser carries.
+ *
+ * @since 0.0.0 @category models
+ */
+export type OAuth2Params<Setup = undefined> =
+  | Readonly<Record<string, string>>
+  | OAuth2ParamsHook<Setup>;
+
+/** @since 0.0.0 @category hooks */
+export type OAuth2HeadersHook<SetupValue> = (
+  context: HookContext<SetupValue>,
+) => Readonly<Record<string, string>>;
+
+/**
+ * Provider headers for token exchange and refresh, fixed or derived from setup.
+ * Hosts must reject invalid headers and case-insensitive overrides of client
+ * authentication and transport headers. Keep values out of authorization URLs,
+ * public metadata, logs, and errors.
+ *
+ * @since 0.0.0 @category models
+ */
+export type OAuth2Headers<SetupValue = HookContext["setup"]> =
+  | Readonly<Record<string, string>>
+  | OAuth2HeadersHook<SetupValue>;
+
+/** @since 0.0.0 @category schemas */
+export const OAuth2ProviderTokenResponse = Schema.Struct({
+  access_token: Schema.optional(Schema.String),
+  expires_at: Schema.optional(Schema.String),
+  expires_in: Schema.optional(Schema.Union([Schema.Number, Schema.String])),
+  refresh_token: Schema.optional(Schema.String),
+  scope: Schema.optional(Schema.String),
+  token_type: Schema.optional(Schema.String),
+});
+
+/** @since 0.0.0 @category models */
+export type OAuth2ProviderTokenResponse = typeof OAuth2ProviderTokenResponse.Type;
+
+/** @since 0.0.0 @category schemas */
+export const OAuth2TokenResponse = Schema.Struct({
+  accessToken: Schema.String,
+  expiresAt: Schema.optional(Schema.Number),
+  expiresIn: Schema.optional(Schema.Number),
+  raw: Schema.Record(Schema.String, Schema.Unknown),
+  refreshToken: Schema.optional(Schema.String),
+  scope: Schema.optional(Schema.String),
+  tokenType: Schema.optional(Schema.String),
+});
+
+/** @since 0.0.0 @category models */
+export type OAuth2TokenResponse = typeof OAuth2TokenResponse.Type;
+
+/** @since 0.0.0 @category errors */
+export class OAuth2RefreshTokenUnavailableError extends Schema.TaggedError<OAuth2RefreshTokenUnavailableError>()(
+  "OAuth2RefreshTokenUnavailableError",
+  { methodIdentifier: Schema.String },
+) {}
+
+/** @since 0.0.0 @category errors */
+export const AuthMethodHookOperation = Schema.Literals([
+  "prepare",
+  "refresh",
+  "prepareOAuth2Tokens",
+  "resolve",
+  "display",
+  "test",
+  "oauth2TokenRefresh",
+]);
+
+/** @since 0.0.0 @category errors */
+export type AuthMethodHookOperation = typeof AuthMethodHookOperation.Type;
+
+/** @since 0.0.0 @category errors */
+export class AuthMethodHookError extends Schema.TaggedError<AuthMethodHookError>()(
+  "AuthMethodHookError",
+  { cause: Schema.Defect(), methodIdentifier: Schema.String, operation: AuthMethodHookOperation },
+) {}
+
+/** @since 0.0.0 @category schemas */
+export const OAuth2TokenMaterial = Schema.Struct({
+  accessToken: Schema.String,
+  expiresAt: Schema.optional(Schema.Number),
+  expiresIn: Schema.optional(Schema.Number),
+  raw: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+  refreshToken: Schema.optional(Schema.String),
+  scope: Schema.optional(Schema.String),
+  tokenType: Schema.optional(Schema.String),
+});
+
+/** @since 0.0.0 @category models */
+export interface OAuth2Setup<
+  MaterialSchema extends Schema.Top,
+  Setup = undefined,
+  TokenRequirements = never,
+> {
+  readonly scopes: readonly string[];
+  readonly client: OAuth2Client<Setup>;
+  readonly discoveryUrl?: OAuth2Endpoint<Setup>;
+  readonly authorizationUrl?: OAuth2Endpoint<Setup>;
+  readonly tokenUrl?: OAuth2Endpoint<Setup>;
+  readonly pkce?: boolean;
+  readonly authorizationParams?: OAuth2Params<Setup>;
+  readonly tokenParams?: OAuth2Params<Setup>;
+  readonly tokenHeaders?: OAuth2Headers<Setup>;
+  /** Token request body encoding. Standard OAuth2 methods use form encoding. */
+  readonly tokenRequestEncoding?: "form" | "json";
+  /** Decode a provider response into the standard token fields before host normalization. */
+  readonly tokenResponse?: Schema.Decoder<OAuth2ProviderTokenResponse>;
+  readonly fromTokens?: PrepareHook<
+    OAuth2TokenResponse,
+    Schema.Schema.Type<MaterialSchema>,
+    any,
+    TokenRequirements,
+    Setup
+  >;
+}
+
+/** @since 0.0.0 @category models */
+export interface OAuth2Options<
+  MaterialSchema extends Schema.Top,
+  ValueSchema extends Schema.Top = MaterialSchema,
+  SetupSchema extends Schema.Top | undefined = undefined,
+  TokenRequirements = never,
+  ResolveRequirements = never,
+  DisplayRequirements = never,
+  TestRequirements = never,
+> extends OAuth2Setup<MaterialSchema, SchemaType<SetupSchema>, TokenRequirements> {
+  readonly name?: string;
+  readonly description?: string;
+  readonly setup?: SetupSchema;
+  readonly material: MaterialSchema;
+  readonly value?: ValueSchema;
+  readonly fromTokens?: PrepareHook<
+    OAuth2TokenResponse,
+    Schema.Schema.Type<MaterialSchema>,
+    any,
+    TokenRequirements,
+    SchemaType<SetupSchema>
+  >;
+  readonly resolve?: ResolveHook<
+    Schema.Schema.Type<MaterialSchema>,
+    Schema.Schema.Type<ValueSchema>,
+    any,
+    ResolveRequirements,
+    SchemaType<SetupSchema>
+  >;
+  readonly display?: DisplayHook<
+    Schema.Schema.Type<MaterialSchema>,
+    any,
+    DisplayRequirements,
+    SchemaType<SetupSchema>
+  >;
+  readonly test?: TestHook<
+    Schema.Schema.Type<MaterialSchema>,
+    any,
+    TestRequirements,
+    SchemaType<SetupSchema>
+  >;
+}
+
+/**
+ * A typed provider-owned auth method definition.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface AuthMethod<
+  out Identifier extends string = string,
+  out SetupSchema extends Schema.Top | undefined = Schema.Top | undefined,
+  out InputSchema extends Schema.Top | undefined = Schema.Top | undefined,
+  out MaterialSchema extends Schema.Top = Schema.Top,
+  out ValueSchema extends Schema.Top = Schema.Top,
+  out Requirements = never,
+>
+  extends Pipeable.Pipeable {
+  readonly [TypeId]: RequirementsVariance<Requirements>;
+  readonly identifier: Identifier;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly kind: AuthMethodKind;
+  readonly setup: SetupSchema;
+  readonly input: InputSchema;
+  readonly material: MaterialSchema;
+  readonly value: ValueSchema;
+  /** Runtime value schema retained for concise action/trigger typing. */
+  readonly schema: ValueSchema;
+  readonly prepare:
+    | PrepareHook<
+        SchemaType<InputSchema>,
+        Schema.Schema.Type<MaterialSchema>,
+        any,
+        Requirements,
+        SchemaType<SetupSchema>
+      >
+    | undefined;
+  readonly refresh:
+    | RefreshHook<Schema.Schema.Type<MaterialSchema>, any, Requirements, SchemaType<SetupSchema>>
+    | undefined;
+  readonly resolve:
+    | ResolveHook<
+        Schema.Schema.Type<MaterialSchema>,
+        Schema.Schema.Type<ValueSchema>,
+        any,
+        Requirements,
+        SchemaType<SetupSchema>
+      >
+    | undefined;
+  readonly display:
+    | DisplayHook<Schema.Schema.Type<MaterialSchema>, any, Requirements, SchemaType<SetupSchema>>
+    | undefined;
+  readonly test:
+    | TestHook<Schema.Schema.Type<MaterialSchema>, any, Requirements, SchemaType<SetupSchema>>
+    | undefined;
+  readonly oauth2: OAuth2Setup<MaterialSchema, SchemaType<SetupSchema>, Requirements> | undefined;
+}
+
+const Proto = { ...PipeableProto, [TypeId]: { _Requirements: Func.identity } };
+
+const makeAuthMethod = <
+  const Identifier extends string,
+  SetupSchema extends Schema.Top | undefined,
+  InputSchema extends Schema.Top | undefined,
+  MaterialSchema extends Schema.Top,
+  ValueSchema extends Schema.Top,
+  TokenRequirements = never,
+  RefreshRequirements = never,
+  PrepareRequirements = never,
+  ResolveRequirements = never,
+  DisplayRequirements = never,
+  TestRequirements = never,
+>(
+  identifier: Identifier,
+  options: {
+    readonly name: string | undefined;
+    readonly description: string | undefined;
+    readonly kind: AuthMethodKind;
+    readonly setup: SetupSchema;
+    readonly input: InputSchema;
+    readonly material: MaterialSchema;
+    readonly value: ValueSchema;
+    readonly prepare:
+      | PrepareHook<
+          SchemaType<InputSchema>,
+          Schema.Schema.Type<MaterialSchema>,
+          any,
+          PrepareRequirements,
+          SchemaType<SetupSchema>
+        >
+      | undefined;
+    readonly refresh:
+      | RefreshHook<
+          Schema.Schema.Type<MaterialSchema>,
+          any,
+          RefreshRequirements,
+          SchemaType<SetupSchema>
+        >
+      | undefined;
+    readonly resolve:
+      | ResolveHook<
+          Schema.Schema.Type<MaterialSchema>,
+          Schema.Schema.Type<ValueSchema>,
+          any,
+          ResolveRequirements,
+          SchemaType<SetupSchema>
+        >
+      | undefined;
+    readonly display:
+      | DisplayHook<
+          Schema.Schema.Type<MaterialSchema>,
+          any,
+          DisplayRequirements,
+          SchemaType<SetupSchema>
+        >
+      | undefined;
+    readonly test:
+      | TestHook<Schema.Schema.Type<MaterialSchema>, any, TestRequirements, SchemaType<SetupSchema>>
+      | undefined;
+    readonly oauth2:
+      | OAuth2Setup<MaterialSchema, SchemaType<SetupSchema>, TokenRequirements>
+      | undefined;
+  },
+): AuthMethod<
+  Identifier,
+  SetupSchema,
+  InputSchema,
+  MaterialSchema,
+  ValueSchema,
+  | TokenRequirements
+  | RefreshRequirements
+  | PrepareRequirements
+  | ResolveRequirements
+  | DisplayRequirements
+  | TestRequirements
+> => {
+  validateIdentifier("auth-method", identifier);
+
+  return Object.assign(Object.create(Proto), {
+    description: options.description,
+    display: options.display,
+    identifier,
+    input: options.input,
+    kind: options.kind,
+    material: options.material,
+    name: options.name,
+    oauth2: options.oauth2,
+    prepare: options.prepare,
+    refresh: options.refresh,
+    resolve: options.resolve,
+    schema: options.value,
+    setup: options.setup,
+    test: options.test,
+    value: options.value,
+  });
+};
+
+/**
+ * Create an {@link AuthMethod} definition.
+ *
+ * @since 0.0.0
+ * @category constructors
+ */
+export const make = <
+  const Identifier extends string,
+  ValueSchema extends Schema.Top,
+  SetupSchema extends Schema.Top | undefined = undefined,
+>(
+  identifier: Identifier,
+  options: FormOptions<ValueSchema, SetupSchema>,
+): AuthMethod<Identifier, SetupSchema, ValueSchema, ValueSchema, ValueSchema> =>
+  form(identifier, options);
+
+/**
+ * Create a simple form auth method where input, stored material, and runtime value share one schema.
+ *
+ * @since 0.0.0
+ * @category constructors
+ */
+export const form = <
+  const Identifier extends string,
+  ValueSchema extends Schema.Top,
+  SetupSchema extends Schema.Top | undefined = undefined,
+>(
+  identifier: Identifier,
+  options: FormOptions<ValueSchema, SetupSchema>,
+): AuthMethod<Identifier, SetupSchema, ValueSchema, ValueSchema, ValueSchema> =>
+  makeAuthMethod(identifier, {
+    description: options.description,
+    display: undefined,
+    input: options.schema,
+    kind: "form",
+    material: options.schema,
+    name: options.name,
+    oauth2: undefined,
+    prepare: undefined,
+    refresh: undefined,
+    resolve: undefined,
+    setup: options.setup as SetupSchema,
+    test: undefined,
+    value: options.schema,
+  });
+
+/**
+ * Create a custom auth setup method.
+ *
+ * @since 0.0.0
+ * @category constructors
+ */
+export function auth<
+  const Identifier extends string,
+  InputSchema extends Schema.Top,
+  ValueSchema extends Schema.Top = InputSchema,
+  SetupSchema extends Schema.Top | undefined = undefined,
+  PrepareRequirements = never,
+  RefreshRequirements = never,
+  ResolveRequirements = never,
+  DisplayRequirements = never,
+  TestRequirements = never,
+>(
+  identifier: Identifier,
+  options: AuthOptionsWithoutMaterial<
+    InputSchema,
+    ValueSchema,
+    SetupSchema,
+    PrepareRequirements,
+    RefreshRequirements,
+    ResolveRequirements,
+    DisplayRequirements,
+    TestRequirements
+  >,
+): AuthMethod<
+  Identifier,
+  SetupSchema,
+  InputSchema,
+  InputSchema,
+  ValueSchema,
+  | PrepareRequirements
+  | RefreshRequirements
+  | ResolveRequirements
+  | DisplayRequirements
+  | TestRequirements
+>;
+export function auth<
+  const Identifier extends string,
+  InputSchema extends Schema.Top | undefined,
+  MaterialSchema extends Schema.Top,
+  ValueSchema extends Schema.Top = MaterialSchema,
+  SetupSchema extends Schema.Top | undefined = undefined,
+  PrepareRequirements = never,
+  RefreshRequirements = never,
+  ResolveRequirements = never,
+  DisplayRequirements = never,
+  TestRequirements = never,
+>(
+  identifier: Identifier,
+  options: AuthOptionsWithMaterial<
+    InputSchema,
+    MaterialSchema,
+    ValueSchema,
+    SetupSchema,
+    PrepareRequirements,
+    RefreshRequirements,
+    ResolveRequirements,
+    DisplayRequirements,
+    TestRequirements
+  >,
+): AuthMethod<
+  Identifier,
+  SetupSchema,
+  InputSchema,
+  MaterialSchema,
+  ValueSchema,
+  | PrepareRequirements
+  | RefreshRequirements
+  | ResolveRequirements
+  | DisplayRequirements
+  | TestRequirements
+>;
+export function auth(
+  identifier: string,
+  options:
+    | AuthOptionsWithoutMaterial<Schema.Top, Schema.Top, any, any, any, any, any, any>
+    | AuthOptionsWithMaterial<
+        Schema.Top | undefined,
+        Schema.Top,
+        Schema.Top,
+        any,
+        any,
+        any,
+        any,
+        any,
+        any
+      >,
+): Any {
+  const material = options.material ?? options.input;
+  if (material === undefined) {
+    throw new Error(`auth method "${identifier}" requires material when input is omitted`);
+  }
+
+  return makeAuthMethod(identifier, {
+    description: options.description,
+    display: options.display,
+    input: options.input,
+    kind: "custom",
+    material,
+    name: options.name,
+    oauth2: undefined,
+    prepare: options.prepare,
+    refresh: options.refresh,
+    resolve: options.resolve,
+    setup: options.setup,
+    test: options.test,
+    value: options.value ?? material,
+  });
+}
+
+/**
+ * Create an OAuth2 auth method over the same setup primitive.
+ *
+ * OAuth2 has no submitted form input; the platform owns the browser redirect,
+ * callback, state/PKCE, and token exchange before storing mapped material.
+ *
+ * @since 0.0.0
+ * @category constructors
+ */
+export const oauth2 = <
+  const Identifier extends string,
+  MaterialSchema extends Schema.Top,
+  ValueSchema extends Schema.Top = MaterialSchema,
+  SetupSchema extends Schema.Top | undefined = undefined,
+  TokenRequirements = never,
+  ResolveRequirements = never,
+  DisplayRequirements = never,
+  TestRequirements = never,
+>(
+  identifier: Identifier,
+  options: OAuth2Options<
+    MaterialSchema,
+    ValueSchema,
+    SetupSchema,
+    TokenRequirements,
+    ResolveRequirements,
+    DisplayRequirements,
+    TestRequirements
+  >,
+): AuthMethod<
+  Identifier,
+  SetupSchema,
+  undefined,
+  MaterialSchema,
+  ValueSchema,
+  // The built-in oauth2 refresh path needs the token refresher service and
+  // re-decodes refreshed material, so those join the user hook requirements.
+  | OAuth2TokenRefresher.Service
+  | Schema.Codec.DecodingServices<MaterialSchema>
+  | TokenRequirements
+  | ResolveRequirements
+  | DisplayRequirements
+  | TestRequirements
+> => {
+  const oauth2Setup: OAuth2Setup<MaterialSchema, SchemaType<SetupSchema>, TokenRequirements> = {
+    client: options.client,
+    scopes: options.scopes,
+    ...(options.discoveryUrl === undefined ? {} : { discoveryUrl: options.discoveryUrl }),
+    ...(options.authorizationUrl === undefined
+      ? {}
+      : { authorizationUrl: options.authorizationUrl }),
+    ...(options.tokenUrl === undefined ? {} : { tokenUrl: options.tokenUrl }),
+    ...(options.pkce === undefined ? {} : { pkce: options.pkce }),
+    ...(options.authorizationParams === undefined
+      ? {}
+      : { authorizationParams: options.authorizationParams }),
+    ...(options.tokenParams === undefined ? {} : { tokenParams: options.tokenParams }),
+    ...(options.tokenHeaders === undefined ? {} : { tokenHeaders: options.tokenHeaders }),
+    ...(options.tokenRequestEncoding === undefined
+      ? {}
+      : { tokenRequestEncoding: options.tokenRequestEncoding }),
+    ...(options.tokenResponse === undefined ? {} : { tokenResponse: options.tokenResponse }),
+    ...(options.fromTokens === undefined ? {} : { fromTokens: options.fromTokens }),
+  };
+
+  return makeAuthMethod(identifier, {
+    description: options.description,
+    display: options.display,
+    input: undefined,
+    kind: "oauth2",
+    material: options.material,
+    name: options.name,
+    oauth2: oauth2Setup,
+    prepare: undefined,
+    refresh: undefined,
+    resolve: options.resolve,
+    setup: options.setup as SetupSchema,
+    test: options.test,
+    value: (options.value ?? options.material) as ValueSchema,
+  });
+};
+
+/**
+ * Check if a value is an {@link AuthMethod}.
+ *
+ * @since 0.0.0
+ * @category guards
+ */
+export const isAuthMethod = (u: unknown): u is Any => Predicate.hasProperty(u, TypeId);
+
+/**
+ * Resolved value type carried by a {@link AuthMethod}.
+ *
+ * @since 0.0.0
+ * @category type-level
+ */
+export type Value<Method extends Any> = Schema.Schema.Type<ValueSchema<Method>>;
+
+/** @since 0.0.0 @category type-level */
+export type Setup<Method extends Any> = SchemaType<SetupSchema<Method>>;
+
+/**
+ * Submitted setup input type carried by an {@link AuthMethod}.
+ *
+ * @since 0.0.0
+ * @category type-level
+ */
+export type Input<Method extends Any> = SchemaType<InputSchema<Method>>;
+
+/**
+ * Encrypted stored material type carried by an {@link AuthMethod}.
+ *
+ * @since 0.0.0
+ * @category type-level
+ */
+export type Material<Method extends Any> = Schema.Schema.Type<MaterialSchema<Method>>;
+
+/**
+ * Schema type carried by a {@link AuthMethod}.
+ *
+ * @since 0.0.0
+ * @category type-level
+ */
+export type ValueSchema<Method extends Any> = Method["value"];
+
+/** @since 0.0.0 @category type-level */
+export type SetupSchema<Method extends Any> = Method["setup"];
+
+/** @since 0.0.0 @category type-level */
+export type InputSchema<Method extends Any> = Method["input"];
+
+/** @since 0.0.0 @category type-level */
+export type MaterialSchema<Method extends Any> = Method["material"];
+
+/**
+ * Services required by the method's hooks, as one union.
+ *
+ * @since 0.0.0
+ * @category type-level
+ */
+export type Requirements<Method extends Any> = Types.Covariant.Type<
+  Method[TypeId]["_Requirements"]
+>;
+
+// Compatibility exports keep the original AuthMethod namespace intact while
+// focused callers can import each runtime module directly.
+export {
+  type Binding,
+  type BindingFor,
+  type BindingForMethod,
+  type MatchCases,
+  type Context,
+  makeBinding,
+  isBindingForMethod,
+} from "./AuthMethodBinding.ts";
+export {
+  decodeValue,
+  decodeSetup,
+  decodeInput,
+  decodeMaterial,
+  prepareDecoded,
+  prepareUnknown,
+  prepare,
+  refreshDecoded,
+  refreshUnknown,
+  prepareOAuth2Tokens,
+  resolveDecoded,
+  resolve,
+  resolveUnknown,
+  display,
+  test,
+} from "./AuthMethodExecution.ts";
+export { Service } from "./OAuth2TokenRefresher.ts";
+export * as OAuth2TokenRefresher from "./OAuth2TokenRefresher.ts";