@qauth-labs/plugin-sdk 0.0.0-stage → 0.2.0-rc.1

package/dist/lib/contract.js

@@ -0,0 +1,285 @@
+/**
+ * The fixed values of the AuthMethod contract (#599, ADR-003 as amended,
+ * ADR-018 §4, ADR-019 Decision 12).
+ *
+ * EXPERIMENTAL. The AuthMethod contract is the plugin API of ADR-018 §4: it is
+ * public and documented, so others can write methods against it, but it stays
+ * outside the 1.0 stability promise and may change in a minor release. It
+ * becomes stable in 1.x. QAuth's experimental-feature registry lists it as
+ * `plugin-api`.
+ *
+ * This package imports no other QAuth package, so the few values it shares
+ * with the server's other contracts (the Interaction API's version label and
+ * display rule, the credential types QAuth writes itself) are written out
+ * here. The server checks at boot, and in its tests, that each still equals
+ * its source.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The contract's name, as it appears in {@link AUTH_METHOD_CONTRACT}.
+ *
+ * @experimental
+ */
+export const AUTH_METHOD_CONTRACT_NAME = 'qauth-auth-method';
+/**
+ * The contract's version: a release candidate until QAuth 1.0.0
+ * (ADR-018 §5). A breaking change raises the release-candidate number, so one
+ * identifier never names two contracts.
+ *
+ * @experimental
+ */
+export const AUTH_METHOD_CONTRACT_VERSION = '1-rc.0';
+/**
+ * The contract a method declares it is written against, as a format id:
+ * `qauth-auth-method/1-rc.0`. The registry refuses a method that declares
+ * another one, so a method built for another version fails the boot instead of
+ * running against a contract it does not know.
+ *
+ * @experimental
+ */
+export const AUTH_METHOD_CONTRACT = `${AUTH_METHOD_CONTRACT_NAME}/${AUTH_METHOD_CONTRACT_VERSION}`;
+/**
+ * The export a plugin package names its method by: `authMethod`, an
+ * AuthMethod object. A CommonJS package may put it under `default`.
+ *
+ * ```ts
+ * // index.ts of @example/qauth-plugin-corp-sso
+ * export const authMethod: AuthMethod<CorpSsoConfig, CorpSsoTransaction> = { … };
+ * ```
+ *
+ * @experimental
+ */
+export const AUTH_METHOD_PLUGIN_EXPORT = 'authMethod';
+/**
+ * The Interaction API's version label, which every step name carries
+ * (ADR-018 §5): `v1-rc.0` until QAuth 1.0.0.
+ */
+const INTERACTION_API_VERSION = 'v1-rc.0';
+/**
+ * The upstream step: the Interaction API step through which a person signs in
+ * at an upstream identity provider. The method starts an upstream transaction
+ * (`AuthMethod.start`), the browser goes to the provider, and the
+ * method's callback route hands the provider's answer back to the engine.
+ *
+ * Step names are QAuth identifiers that carry the Interaction API's version
+ * (ADR-018 §5): `urn:qauth:ia:upstream:v1-rc.0` until 1.0.0. The step's params
+ * and its place in ADR-017's step table come with the upstream sign-in flow
+ * (#639).
+ *
+ * @experimental
+ */
+export const UPSTREAM_STEP_URN = `urn:qauth:ia:upstream:${INTERACTION_API_VERSION}`;
+/**
+ * Every step a method may contribute in this version of the contract, by URN.
+ * Only the upstream step today; a later version may add others (an LDAP form,
+ * for instance).
+ *
+ * @experimental
+ */
+export const AUTH_METHOD_STEP_URNS = Object.freeze([UPSTREAM_STEP_URN]);
+/**
+ * The root every method's routes are mounted under, on the realm host. A
+ * method's own prefix is `/upstream/<type>` ({@link authMethodRoutePrefix}),
+ * so each provider has its own callback URL, and a response meant for one
+ * provider cannot be replayed at another.
+ *
+ * No version in the path: the callback URL is registered at the upstream
+ * provider, and a path that changed at 1.0 would break every registration.
+ *
+ * @experimental
+ */
+export const AUTH_METHOD_ROUTE_ROOT = '/upstream';
+/**
+ * The prefix a method's routes are mounted under: `/upstream/<type>`.
+ *
+ * @experimental
+ */
+export function authMethodRoutePrefix(type) {
+    if (!AUTH_METHOD_TYPE_PATTERN.test(type)) {
+        throw new TypeError('not an AuthMethod type');
+    }
+    return `${AUTH_METHOD_ROUTE_ROOT}/${type}`;
+}
+/**
+ * An AuthMethod's `type`: lower-case ASCII letters, digits and `_`, starting
+ * with a letter, at most 63 characters. It is the registry key, the value
+ * written to `user_credentials.provider_type`, the `source` of the attributes
+ * the method extracts and a segment of its route prefix, so it must be safe in
+ * all four. A type with `:` or `/` (an ID-JAG issuer type, `oidc_<issuer URL>`)
+ * can never match.
+ *
+ * @experimental
+ */
+export const AUTH_METHOD_TYPE_PATTERN = /^[a-z][a-z0-9_]{0,62}$/;
+/**
+ * An AuthMethod's `id`: the stable name of the method's implementation, such
+ * as `oidc` or `corp-sso`. Lower-case ASCII letters, digits, `_` and `-`,
+ * starting with a letter, at most 63 characters.
+ *
+ * @experimental
+ */
+export const AUTH_METHOD_ID_PATTERN = /^[a-z][a-z0-9_-]{0,62}$/;
+/**
+ * Types an AuthMethod may not take: the credential types and the attribute
+ * source QAuth writes itself, built or planned. A method under one of them
+ * would read as that built-in credential, and `wallet` would outrank every
+ * other attribute source in claim resolution (`rankAttributeSource`).
+ *
+ * @experimental
+ */
+export const RESERVED_AUTH_METHOD_TYPES = Object.freeze([
+    'password',
+    'wallet',
+    'webauthn',
+    'self_reported',
+    'totp',
+    'recovery_code',
+    'email_code',
+]);
+/**
+ * A route path below a method's prefix: one to four segments of lower-case
+ * ASCII letters, digits, `_` and `-`, such as `/callback`. No dot segment, no
+ * encoded character, no route parameter and no wildcard can match, so a path
+ * cannot leave the prefix it is mounted under.
+ *
+ * @experimental
+ */
+export const AUTH_METHOD_ROUTE_PATH_PATTERN = /^(?:\/[a-z0-9][a-z0-9_-]{0,62}){1,4}$/;
+/**
+ * The display rule of the Interaction API (ADR-019 Decision 6), which a
+ * method's default name follows: no markup bracket, no control, format,
+ * private-use or unassigned character, no line separator and no space at
+ * either end.
+ *
+ * @experimental
+ */
+export const AUTH_METHOD_DISPLAY_NAME_PATTERN = /^[^<>\p{C}\p{Z}\u115F\u1160\u3164\uFFA0](?:[^<>\p{C}\p{Zl}\p{Zp}\u115F\u1160\u3164\uFFA0]*[^<>\p{C}\p{Z}\u115F\u1160\u3164\uFFA0])?$/u;
+/**
+ * The longest default display name, in UTF-16 code units.
+ *
+ * @experimental
+ */
+export const MAX_AUTH_METHOD_DISPLAY_NAME_LENGTH = 64;
+/**
+ * The largest default icon, in bytes.
+ *
+ * @experimental
+ */
+export const MAX_AUTH_METHOD_ICON_BYTES = 16 * 1024;
+/**
+ * The media types a default icon may have: raster PNG only. An SVG can carry
+ * script, and the icon is served from the realm origin.
+ *
+ * @experimental
+ */
+export const AUTH_METHOD_ICON_MEDIA_TYPES = Object.freeze(['image/png']);
+/**
+ * The largest upstream transaction a method may ask the engine to keep, in
+ * bytes of its JSON form. The engine stores it server-side, bound to the
+ * interaction and its flow cookie, for the lifetime of the interaction.
+ *
+ * @experimental
+ */
+export const MAX_UPSTREAM_TRANSACTION_BYTES = 4096;
+/**
+ * A binding (#599): the value `start()` answers beside its transaction, which
+ * the authorization request carries to the provider (as `state`, usually)
+ * and the provider's callback carries back. 22 to 512 base64url characters:
+ * 22 is the length of 128 random bits in base64url. The pattern checks the
+ * length and the alphabet only; the method makes the value random.
+ *
+ * @experimental
+ */
+export const AUTH_METHOD_BINDING_PATTERN = /^[A-Za-z0-9_-]{22,512}$/;
+/**
+ * The parameter a callback route carries the binding back in when the route
+ * names none: `state` (RFC 6749 §4.1.2).
+ *
+ * @experimental
+ */
+export const DEFAULT_AUTH_METHOD_BINDING_PARAMETER = 'state';
+/**
+ * A parameter name a callback route may name as its binding parameter:
+ * ASCII letters, digits, `_`, `.` and `-`, at most 64 characters.
+ *
+ * @experimental
+ */
+export const AUTH_METHOD_BINDING_PARAMETER_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+/**
+ * The longest URL a method may send the browser to when it starts.
+ *
+ * @experimental
+ */
+export const MAX_UPSTREAM_REDIRECT_LENGTH = 8192;
+/**
+ * The longest `externalSub` a method may resolve: 255 characters, the limit
+ * OpenID Connect Core 1.0 §2 sets on `sub`.
+ *
+ * @experimental
+ */
+export const MAX_AUTH_METHOD_EXTERNAL_SUB_LENGTH = 255;
+/**
+ * The largest `rawClaims` a method's `verify()` may resolve, in bytes of its
+ * JSON form. The engine keeps a frozen copy.
+ *
+ * @experimental
+ */
+export const MAX_AUTH_METHOD_RAW_CLAIMS_BYTES = 64 * 1024;
+/**
+ * An attribute key a method may extract: lower-case ASCII letters, digits
+ * and `_`, starting with a letter, at most 64 characters (`email`,
+ * `given_name`).
+ *
+ * @experimental
+ */
+export const AUTH_METHOD_ATTRIBUTE_KEY_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+/**
+ * The longest attribute value a method may extract, in UTF-16 code units.
+ *
+ * @experimental
+ */
+export const MAX_AUTH_METHOD_ATTRIBUTE_VALUE_LENGTH = 8192;
+/**
+ * The most parameters a method's route handler sees from one query or one
+ * form; the rest are dropped.
+ *
+ * @experimental
+ */
+export const MAX_AUTH_METHOD_PARAMETERS = 64;
+/**
+ * The longest parameter value a method's route handler sees, in UTF-16 code
+ * units; a parameter with a longer value is dropped.
+ *
+ * @experimental
+ */
+export const MAX_AUTH_METHOD_PARAMETER_LENGTH = 8192;
+/**
+ * The most values of one repeated parameter a method's route handler sees;
+ * a parameter repeated more often is dropped.
+ *
+ * @experimental
+ */
+export const MAX_AUTH_METHOD_PARAMETER_VALUES = 16;
+/**
+ * Why a method's callback did not produce a result, other than the person
+ * declining at the provider:
+ *
+ * - `transaction_mismatch`: no transaction is pending for this browser, or the
+ *   callback does not belong to it (its binding, `state` by default, is
+ *   missing, repeated or another's). A callback replayed in another browser,
+ *   or forged, ends here; the host answers it before the method runs.
+ * - `provider_error`: the provider answered with an error, other than the
+ *   person declining (`access_denied`).
+ * - `invalid_response`: the provider's answer failed a check, such as the ID
+ *   token's signature, `iss`, `aud` or `nonce`.
+ * - `upstream_unavailable`: the provider could not be reached in time.
+ *
+ * @experimental
+ */
+export const UPSTREAM_FAILURE_REASONS = Object.freeze([
+    'transaction_mismatch',
+    'provider_error',
+    'invalid_response',
+    'upstream_unavailable',
+]);

package/dist/lib/credential-provider.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The verification half of a sign-in method (ADR-003): what every provider
+ * QAuth registers implements, and what an AuthMethod extends.
+ *
+ * The auth engine depends only on this contract: it resolves a provider by
+ * `type`, calls `verify()`, and upserts the attributes from
+ * `extractAttributes()`. It contains no provider-specific logic, so new
+ * providers are added without changing the engine.
+ *
+ * EXPERIMENTAL as part of this package, the plugin API of ADR-018 §4: it may
+ * change in a minor release.
+ *
+ * @see https://docs.qauth.dev/reference/records/adr/003-credential-provider-interface/
+ */
+/**
+ * Level of assurance for a verified identity, aligned with eIDAS Levels of
+ * Assurance (LoA) and ISO/IEC 29115. Propagated downstream as the OIDC `acr`
+ * claim; `'low'` credentials (e.g. self-asserted email/password) carry no `acr`
+ * claim per ADR-003.
+ *
+ * @experimental
+ */
+export type AssuranceLevel = 'low' | 'substantial' | 'high';
+/**
+ * The result of a successful {@link CredentialProvider.verify} call: a
+ * provider-scoped subject identifier, the assurance level of the verification,
+ * and the raw claims the provider observed.
+ *
+ * @experimental
+ */
+export interface VerifiedIdentity {
+    /**
+     * Subject identifier as known to the upstream provider (e.g. the normalized
+     * email for password, a DID for a wallet). Never used directly as the token
+     * `sub` — the engine maps it to the internal `users.id`.
+     */
+    externalSub: string;
+    /** Assurance level of this verification (eIDAS LoA / ISO 29115). */
+    assuranceLevel: AssuranceLevel;
+    /** Unprocessed claims exactly as returned by the provider, before extraction. */
+    rawClaims: Record<string, unknown>;
+}
+/**
+ * A single normalized user attribute derived from a {@link VerifiedIdentity},
+ * ready to be upserted into `user_attributes`. Trust ordering during claim
+ * resolution is driven by `source` and `verified`.
+ *
+ * @experimental
+ */
+export interface UserAttribute {
+    /**
+     * Origin of the attribute (e.g. `'self_reported'`, `'wallet'`,
+     * `'oidc_google'`). Drives trust ordering during claim resolution.
+     */
+    source: string;
+    /** Attribute key (e.g. `'email'`). */
+    attrKey: string;
+    /** Attribute value. */
+    attrValue: string;
+    /** Whether the provider verified this attribute. */
+    verified: boolean;
+    /** Optional expiry after which the attribute must be re-verified. */
+    expiresAt?: Date;
+}
+/**
+ * Strategy interface implemented by every authentication method (ADR-003).
+ *
+ * @experimental
+ */
+export interface CredentialProvider {
+    /**
+     * Stable discriminator the server's provider registry registers and
+     * resolves this provider by (e.g. `'password'`, `'wallet'`).
+     */
+    readonly type: string;
+    /**
+     * Verify the provider-specific `input` and resolve a normalized
+     * {@link VerifiedIdentity}. Implementations reject on verification failure.
+     */
+    verify(input: unknown): Promise<VerifiedIdentity>;
+    /**
+     * Derive normalized {@link UserAttribute} rows from a successful verification
+     * result, ready to be upserted into `user_attributes`.
+     */
+    extractAttributes(result: VerifiedIdentity): UserAttribute[];
+}

package/dist/lib/credential-provider.js

@@ -0,0 +1,15 @@
+/**
+ * The verification half of a sign-in method (ADR-003): what every provider
+ * QAuth registers implements, and what an AuthMethod extends.
+ *
+ * The auth engine depends only on this contract: it resolves a provider by
+ * `type`, calls `verify()`, and upserts the attributes from
+ * `extractAttributes()`. It contains no provider-specific logic, so new
+ * providers are added without changing the engine.
+ *
+ * EXPERIMENTAL as part of this package, the plugin API of ADR-018 §4: it may
+ * change in a minor release.
+ *
+ * @see https://docs.qauth.dev/reference/records/adr/003-credential-provider-interface/
+ */
+export {};

package/dist/lib/engine.d.ts

@@ -0,0 +1,125 @@
+import type { AuthMethod, AuthMethodContext, AuthMethodRoute, AuthMethodRouteRequest, UpstreamStart, UpstreamStartRequest } from './auth-method.js';
+import { type UpstreamFailureReason } from './contract.js';
+import type { AssuranceLevel, UserAttribute, VerifiedIdentity } from './credential-provider.js';
+/**
+ * Why the upstream step ended without an identity: a callback's reason, or
+ * `verification_refused` when `verify()` rejected the callback's result.
+ *
+ * @experimental
+ */
+export type UpstreamStepFailureReason = UpstreamFailureReason | 'verification_refused';
+/**
+ * How the upstream step ended, as the sign-in flow acts on it:
+ *
+ * - `identity`: a checked `VerifiedIdentity` and its attributes, each with
+ *   `source` equal to the method's `type`. The flow looks the credential up by
+ *   `(realm, type, externalSub)`; it never matches an account by an attribute.
+ * - `declined`: the person cancelled or declined at the provider.
+ * - `failed`: anything else. `cause` is `verify()`'s rejection, for the log.
+ *
+ * @experimental
+ */
+export type UpstreamStepCompletion = {
+    readonly kind: 'identity';
+    readonly identity: VerifiedIdentity;
+    readonly attributes: readonly UserAttribute[];
+} | {
+    readonly kind: 'declined';
+} | {
+    readonly kind: 'failed';
+    readonly reason: UpstreamStepFailureReason;
+    readonly cause?: unknown;
+};
+/**
+ * Start an upstream transaction: call `method.start()` and check its answer.
+ * The redirect must be an absolute `https` URL with no credentials and no
+ * fragment, the transaction JSON data within its cap, and the binding 22 to
+ * 512 base64url characters. The returned transaction is a frozen copy; the
+ * host stores it with the binding (a `PendingUpstreamTransaction`).
+ *
+ * A rejection of `start()` (the provider's discovery document cannot be read,
+ * for instance) propagates unchanged.
+ *
+ * @throws AuthMethodFaultError when the answer fails a check
+ * @experimental
+ */
+export declare function startUpstreamStep<TConfig, TTransaction>(method: AuthMethod<TConfig, TTransaction>, request: UpstreamStartRequest, context: AuthMethodContext<TConfig>): Promise<UpstreamStart<TTransaction>>;
+/**
+ * The binding a request to `route` carries: the single value of the route's
+ * binding parameter (`state` unless the route names another), from the
+ * query of a `GET` route and the form of a `POST` one. `undefined` when the
+ * parameter is missing or repeated, or `route` is not a callback route.
+ *
+ * @experimental
+ */
+export declare function presentedUpstreamBinding(route: AuthMethodRoute, request: Pick<AuthMethodRouteRequest, 'query' | 'form'>): string | undefined;
+/**
+ * Whether the binding a callback carried is the pending transaction's, in
+ * constant time (`timingSafeEqual` over the UTF-8 bytes). `false` unless both are strings and
+ * the expected one is a binding: a missing or repeated parameter never
+ * matches, and neither does an empty one.
+ *
+ * The host runs it before it takes the transaction, so a callback from
+ * another site cannot spend or cancel a pending sign-in.
+ *
+ * @experimental
+ */
+export declare function upstreamBindingMatches(expected: unknown, presented: unknown): boolean;
+/**
+ * The lowest assurance level, the ceiling of a method's identity when the
+ * caller names none.
+ *
+ * @experimental
+ */
+export declare const DEFAULT_UPSTREAM_MAX_ASSURANCE: AssuranceLevel;
+/**
+ * Options of {@link completeUpstreamStep}.
+ *
+ * @experimental
+ */
+export interface UpstreamStepCompletionOptions {
+    /**
+     * The highest assurance level the identity may carry: a method that
+     * resolves a higher one is lowered to it. Default
+     * {@link DEFAULT_UPSTREAM_MAX_ASSURANCE} (`low`).
+     *
+     * The assurance level reaches `acr` and step-up, so a method does not get
+     * to set it alone. The owner's decision of 23 Oct 2026 ranks an upstream
+     * sign-in with a password, so by default it counts as `low` whatever the
+     * method claims; an operator raises the ceiling for a configured provider
+     * it trusts more (the plugin runtime and the upstream sign-in flow, #600
+     * and #639, pass it).
+     */
+    readonly maxAssurance?: AssuranceLevel;
+}
+/**
+ * Turn what a method's callback handed back into the end of the upstream
+ * step. A `result` goes to `method.verify()`; the identity it resolves is
+ * checked and its assurance level lowered to `options.maxAssurance`, then
+ * `method.extractAttributes()` gives its attributes, which are checked too.
+ *
+ * @param outcome - what the callback route's handler returned, unchecked, or
+ *   the {@link AuthMethodFaultError} the route mount made of a handler that
+ *   threw or a context that could not be built
+ * @param options - the assurance ceiling
+ * @throws AuthMethodFaultError when the outcome is a fault or outside the
+ *   closed set, or the identity or an attribute fails a check
+ * @throws TypeError when `options.maxAssurance` is not an assurance level
+ * @experimental
+ */
+export declare function completeUpstreamStep(method: AuthMethod, outcome: unknown, options?: UpstreamStepCompletionOptions): Promise<UpstreamStepCompletion>;
+/**
+ * Why `value` cannot be where an upstream step sends the browser, or
+ * `undefined` when it can.
+ *
+ * @experimental
+ */
+export declare function upstreamRedirectProblem(value: unknown): string | undefined;
+/**
+ * A frozen copy of `value` when it is JSON data within the transaction cap:
+ * plain objects, arrays, strings, finite numbers, booleans and `null`, nested
+ * at most 16 deep. `undefined` otherwise.
+ *
+ * @experimental
+ */
+export declare function storableTransaction(value: unknown): unknown;