@ultimat3/auth 29.4.0 → 30.0.0

package/src/mfa.ts

@@ -4,7 +4,7 @@
 // and single-use, so a database dump is not a permanent MFA bypass; consuming one is the
 // adapter's (`consumeRecoveryCode`), because single-use has to be one atomic step.
 
-import { finiteCount, timingSafeEqual } from '@ultimat3/core';
+import { finiteCount, hmac, timingSafeEqual } from '@ultimat3/core';
 import type { Auth } from './auth';
 import { mfaSecretInvalid } from './errors';
 import { assertFiniteAuthCount } from './policy-numbers';
@@ -135,9 +135,7 @@ export function totpCode(secret: string, step: number, digits: number = TOTP_DIG
   // code every other unreadable secret answers too. There is no code an unreadable secret is
   // entitled to, so this returns none.
   if (key.length === 0) throw mfaSecretInvalid('totpCode');
-  const mac = Uint8Array.from(
-    new Bun.CryptoHasher('sha1', key).update(counterBytes(step)).digest(),
-  );
+  const mac = hmac('sha1', key, counterBytes(step));
   const offset = (mac[mac.length - 1] ?? 0) & 0x0f;
   const binary =
     (((mac[offset] ?? 0) & 0x7f) << 24) |
@@ -149,7 +147,7 @@ export function totpCode(secret: string, step: number, digits: number = TOTP_DIG
 
 export interface TotpVerification {
   readonly ok: boolean;
-  /** The step the code belonged to — feed it to `TotpReplayGuard.remember()`. */
+  /** The step the code belonged to — what `TotpReplayGuard.claim()` is asked to spend. */
   readonly step: number | null;
 }
 
@@ -191,14 +189,23 @@ export function verifyTotp(input: VerifyTotpInput): TotpVerification {
   return { ok: false, step: null };
 }
 
+/**
+ * One atomic question: spend this step. A check and a write are two round trips across a network,
+ * and two replicas can both pass the check between them, so the guard has no separate read.
+ */
 export interface TotpReplayGuard {
-  isUsed(subject: string, step: number): boolean;
-  remember(subject: string, step: number, at: Date): void;
+  /**
+   * `true` the first time a subject spends a step, `false` for a replay. `at` is the caller's clock
+   * reading. A store that cannot answer REJECTS: a down database is not a wrong code.
+   */
+  claim(subject: string, step: number, at: Date): Promise<boolean>;
 }
 
-/** What `memoryTotpReplayGuard` returns: the interface, plus the bound it keeps, observable. */
+/** What `memoryTotpReplayGuard` returns: the interface, plus the table it keeps, observable. */
 export interface MemoryTotpReplayGuard extends TotpReplayGuard {
   readonly size: number;
+  /** For a test reading the eviction order. Nothing on the sign-in path asks this: `claim` does. */
+  isUsed(subject: string, step: number): boolean;
 }
 
 /**
@@ -233,9 +240,9 @@ const newestStep = (steps: ReadonlySet<number>): number => {
 };
 
 /**
- * In-memory by default because a single web process is the common case; a multi-process
- * deployment passes a Redis-backed guard with the same two methods. Steps older than the
- * drift window are dropped — nothing outside it can be replayed anyway.
+ * One process' table: the default when no host installed a guard, so a code is single-use per
+ * replica. A framework boot installs `postgresTotpReplayGuard` instead (`configureTotpReplay`).
+ * Steps older than the drift window are dropped — nothing outside it can be replayed anyway.
  *
  * Bounded, because the subject map only ever grew: pruning happened inside one subject's `Set`
  * and never revisited a subject who stopped signing in, so the table carried one permanent entry
@@ -270,7 +277,7 @@ export function memoryTotpReplayGuard(
       if (steps.size === 0) used.delete(subject);
     }
     if (used.size <= cap) return;
-    // Map iteration is insertion order and `remember` re-files the subject it touches, so this
+    // Map iteration is insertion order and `claim` re-files the subject it touches, so this
     // sort — stable by specification — breaks a tie on the newest step by least recently seen.
     // Both keys point the same way: the subject who just proved a code is the last one out.
     const furthest = [...used.entries()].sort((a, b) => newestStep(a[1]) - newestStep(b[1]));
@@ -285,7 +292,10 @@ export function memoryTotpReplayGuard(
       return used.size;
     },
     isUsed: (subject, step) => used.get(subject)?.has(step) === true,
-    remember: (subject, step, at) => {
+    // `async` with no `await` in the body: it runs to its `return` in one turn, so two concurrent
+    // completions carrying one code cannot both find the step unspent.
+    claim: async (subject, step, at) => {
+      if (used.get(subject)?.has(step) === true) return false;
       const now = totpStep(at);
       const floor = now - drift;
       const steps = used.get(subject) ?? new Set<number>();
@@ -296,6 +306,7 @@ export function memoryTotpReplayGuard(
       used.delete(subject);
       used.set(subject, steps);
       if (used.size > cap || now - lastSweepStep >= SWEEP_EVERY_STEPS) sweep(now, floor);
+      return true;
     },
   };
 }

package/src/oauth-bearer-resolver.ts

@@ -0,0 +1,44 @@
+// Single responsibility: an authorization server's access token → who is calling, in the shape a
+// bearer mount and an MCP endpoint both take as `resolveToken`. The `Actor` is built PER CALL by
+// the app's `actor`, never stored with the grant: a member removed from the org loses access on
+// the next request with no sweep. `resource`, when given, refuses a token bound to anything else.
+
+import type { Actor } from '@ultimat3/core';
+import type { ResolvedGrant } from './authorization-server-types';
+
+/** Structurally `@ultimat3/http`'s `BearerCaller` and `@ultimat3/mcp`'s `ResolvedToken`. */
+export interface OAuthBearerCaller {
+  readonly actor: Actor;
+  /** What the person (or machine) granted — the mount's scope map is cut by these. */
+  readonly scopes: ReadonlySet<string>;
+}
+
+export interface OAuthBearerResolverOptions {
+  /**
+   * Required: what a subject is NOW. `null` refuses the token — a removed member, a disabled
+   * account, a client the app no longer trusts. `grant.subject` is the client id itself for a
+   * `client_credentials` token.
+   */
+  readonly actor: (grant: ResolvedGrant) => Promise<Actor | null> | Actor | null;
+  /** RFC 8707: accept only tokens bound to this resource. Unbound tokens are refused too. */
+  readonly resource?: string | undefined;
+}
+
+/** What it needs of `authorizationServer()` — its `resolve`, and nothing else. */
+export interface OAuthTokenSource {
+  resolve(token: string): Promise<ResolvedGrant | null>;
+}
+
+export function oauthBearerResolver(
+  server: OAuthTokenSource,
+  options: OAuthBearerResolverOptions,
+): (token: string) => Promise<OAuthBearerCaller | null> {
+  return async (token) => {
+    const grant = await server.resolve(token);
+    if (grant === null) return null;
+    if (options.resource !== undefined && grant.resource !== options.resource) return null;
+    const actor = await options.actor(grant);
+    if (actor === null) return null;
+    return { actor, scopes: grant.scopes };
+  };
+}

package/src/oauth-cookie.ts

@@ -8,6 +8,7 @@
 import type { Clock } from '@ultimat3/core';
 import {
   EnvMissingError,
+  hmac,
   readCookie,
   serializeSetCookie,
   systemClock,
@@ -227,7 +228,7 @@ export function readHandshakeCookie(
 
 /** Keyed SHA-256. Untruncated, unlike a cursor's: a cookie has room and this authorises a login. */
 function sign(body: string, secret: string): string {
-  return new Bun.CryptoHasher('sha256', secret).update(body).digest('hex');
+  return hmac('sha256', secret, body, 'hex');
 }
 
 function parseBody(body: string, provider: OAuthProviderId): unknown {

package/src/oauth-discovery.ts

@@ -9,6 +9,7 @@ import {
   renderFixShellArg,
   renderThrowable,
 } from '@ultimat3/core';
+import { outboundResponse } from '@ultimat3/core/outbound';
 import { isRecord } from './json';
 import type { OAuthProvider, TokenEndpointAuth } from './oauth';
 import { oauthExchangeFailed } from './oauth-errors';
@@ -71,7 +72,9 @@ export async function discoverOAuthProvider(
   // `renderFixLiteral` is the wrong tool for a command, because its double quotes leave `$(…)`
   // live.
   const target = renderFixShellArg(url, '<issuer>/.well-known/openid-configuration');
-  const doFetch: OAuthFetch = input.fetch ?? ((target, init) => globalThis.fetch(target, init));
+  const doFetch: OAuthFetch =
+    input.fetch ??
+    ((target, init) => globalThis.fetch(target, { ...init, signal: init.signal ?? null }));
   // Screened OUTSIDE the try below, deliberately: `AbortSignal.timeout(NaN)` throws, and the
   // catch around this fetch renders every throw as a provider failure — so a typo in the app's
   // own config read as the identity provider being unreachable.
@@ -84,11 +87,19 @@ export async function discoverOAuthProvider(
 
   let response: Response;
   try {
-    response = await doFetch(url, {
-      method: 'GET',
-      headers: { Accept: 'application/json' },
-      signal: AbortSignal.timeout(timeoutMs),
-    });
+    // Through core's `outbound()`: `timeoutMs` bounds the whole call, the ambient request's signal
+    // ends it, a GET's 5xx is retried inside that bound (a POST never is), a 3xx is never followed.
+    response = await outboundResponse(
+      {
+        url: url,
+        vendor: input.id,
+        dial: 'named',
+        deadlineMs: timeoutMs,
+        method: 'GET',
+        headers: { Accept: 'application/json' },
+      },
+      { fetch: doFetch },
+    );
   } catch (error) {
     throw oauthExchangeFailed({
       provider: input.id,

package/src/oauth-exchange.ts

@@ -12,6 +12,7 @@ import {
   renderThrowable,
   systemClock,
 } from '@ultimat3/core';
+import { outboundResponse } from '@ultimat3/core/outbound';
 import { type IdTokenClaims, verifyIdToken } from './id-token';
 import { isRecord } from './json';
 import { type IdTokenKeys, providerJwks } from './jwks';
@@ -185,7 +186,9 @@ async function postForm(
   options: OAuthExchangeOptions,
   authorization?: string,
 ): Promise<Record<string, unknown>> {
-  const doFetch: OAuthFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  const doFetch: OAuthFetch =
+    options.fetch ??
+    ((input, init) => globalThis.fetch(input, { ...init, signal: init.signal ?? null }));
   // Screened OUTSIDE the try below, deliberately: `AbortSignal.timeout(NaN)` throws, and the
   // catch around this fetch renders every throw as a provider failure — so a typo in the app's
   // own config read as the identity provider being unreachable.
@@ -199,18 +202,26 @@ async function postForm(
 
   let response: Response;
   try {
-    response = await doFetch(url, {
-      method: 'POST',
-      headers: {
-        // GitHub answers `application/x-www-form-urlencoded` unless asked for JSON.
-        Accept: 'application/json',
-        'Content-Type': 'application/x-www-form-urlencoded',
-        'User-Agent': OAUTH_USER_AGENT,
-        ...(authorization === undefined ? {} : { Authorization: authorization }),
+    // Through core's `outbound()`: `timeoutMs` bounds the whole call, the ambient request's signal
+    // ends it, a GET's 5xx is retried inside that bound (a POST never is), a 3xx is never followed.
+    response = await outboundResponse(
+      {
+        url: url,
+        vendor: provider,
+        dial: 'named',
+        deadlineMs: timeoutMs,
+        method: 'POST',
+        headers: {
+          // GitHub answers `application/x-www-form-urlencoded` unless asked for JSON.
+          Accept: 'application/json',
+          'Content-Type': 'application/x-www-form-urlencoded',
+          'User-Agent': OAUTH_USER_AGENT,
+          ...(authorization === undefined ? {} : { Authorization: authorization }),
+        },
+        body: body.toString(),
       },
-      body: body.toString(),
-      signal: AbortSignal.timeout(timeoutMs),
-    });
+      { fetch: doFetch },
+    );
   } catch (error) {
     // The rendered value goes to the LOG, never into the `detail:`.
     //

package/src/oauth-profile.ts

@@ -4,6 +4,7 @@
 // decides whether this login may attach itself to an existing account by address.
 
 import { logger, renderFixShellArg, renderThrowable } from '@ultimat3/core';
+import { outboundResponse } from '@ultimat3/core/outbound';
 import { idTokenEmailVerified, isVerifiedFlag } from './id-token';
 import { isRecord } from './json';
 import type { OAuthProviderId } from './oauth';
@@ -53,7 +54,9 @@ async function getJson(
   accessToken: string,
   options: OAuthProfileOptions,
 ): Promise<{ ok: true; body: unknown } | { ok: false; status: number; detail: string }> {
-  const doFetch: OAuthFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  const doFetch: OAuthFetch =
+    options.fetch ??
+    ((input, init) => globalThis.fetch(input, { ...init, signal: init.signal ?? null }));
   // Screened OUTSIDE the try below, deliberately: `AbortSignal.timeout(NaN)` throws, and the
   // catch around this fetch renders every throw as a provider failure — so a typo in the app's
   // own config read as the identity provider being unreachable.
@@ -65,15 +68,23 @@ async function getJson(
   );
   let response: Response;
   try {
-    response = await doFetch(url, {
-      method: 'GET',
-      headers: {
-        Accept: 'application/json',
-        Authorization: `Bearer ${accessToken}`,
-        'User-Agent': OAUTH_USER_AGENT,
+    // Through core's `outbound()`: `timeoutMs` bounds the whole call, the ambient request's signal
+    // ends it, a GET's 5xx is retried inside that bound (a POST never is), a 3xx is never followed.
+    response = await outboundResponse(
+      {
+        url: url,
+        vendor: provider,
+        dial: 'named',
+        deadlineMs: timeoutMs,
+        method: 'GET',
+        headers: {
+          Accept: 'application/json',
+          Authorization: `Bearer ${accessToken}`,
+          'User-Agent': OAUTH_USER_AGENT,
+        },
       },
-      signal: AbortSignal.timeout(timeoutMs),
-    });
+      { fetch: doFetch },
+    );
   } catch (error) {
     // `renderThrowable`, never `error.message` behind an `instanceof`: `fetch` is INJECTED here,
     // so the rejection is whatever a driver or a proxy threw — and `instanceof` runs the value's

package/src/oauth-route.ts

@@ -376,10 +376,10 @@ async function callbackHandler(
   const clear = hasOAuthProvider(segment) ? [clearHandshakeCookie(segment)] : [];
   try {
     const provider = assertEnabled(auth, segment);
-    // Asked here purely so a provider with no credentials answers 404 on THIS leg too: the
-    // exchange below resolves them again from the same two sources. One oracle, closed on both
-    // halves — a 404 on start and a 500 on callback is the same enumeration one request later.
-    credentialsFor(provider, options);
+    // A provider with no credentials answers 404 on THIS leg too: one oracle, closed on both halves
+    // — a 404 on start and a 500 on callback is the same enumeration one request later. And the
+    // answer is what the exchange uses, or `options.env` would answer the start leg alone.
+    const credentials = credentialsFor(provider, options);
     const url = new URL(request.url);
     assertNoProviderError(url, provider);
     const result: LoginResult = await completeOAuthLogin(auth, {
@@ -388,7 +388,7 @@ async function callbackHandler(
         state: url.searchParams.get('state') ?? '',
         code: url.searchParams.get('code') ?? '',
       },
-      ...(options.credentials === undefined ? {} : { credentials: options.credentials }),
+      credentials,
       ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
       ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
       ...(options.resolveGrants === undefined ? {} : { resolveGrants: options.resolveGrants }),

package/src/passkey-assertion.ts

@@ -0,0 +1,60 @@
+// Single responsibility: accepting an assertion against a STORED credential — owner, signature,
+// user handle, and the signature counter's non-regression, advanced compare-and-set. Shared by
+// sign-in and step-up, so the two can never disagree about what a valid assertion is.
+
+import { logger } from '@ultimat3/core';
+import type { PasskeyCredential } from './adapter';
+import type { Auth } from './auth';
+import type { PasskeyRelyingParty } from './passkey-config';
+import { refusePasskey } from './passkey-errors';
+import { type CeremonyEnvelope, type VerifiedAssertion, verifyAssertion } from './passkey-verify';
+
+export interface AcceptedAssertion {
+  readonly credential: PasskeyCredential;
+  readonly assertion: VerifiedAssertion;
+}
+
+/**
+ * `expectedUserId` is the account the ceremony was issued to (step-up), or `null` when the
+ * credential names its own (usernameless sign-in) — then the returned `userHandle`, when the
+ * authenticator sent one, must agree with the stored owner.
+ */
+export async function acceptAssertion(
+  auth: Auth,
+  policy: PasskeyRelyingParty,
+  ceremony: 'login' | 'step-up',
+  envelope: CeremonyEnvelope,
+  expectedUserId: string | null,
+): Promise<AcceptedAssertion> {
+  const credential = await auth.adapter.findPasskey(envelope.credentialId);
+  if (credential === null) throw refusePasskey(ceremony, 'credential-unknown');
+  if (expectedUserId !== null && credential.userId !== expectedUserId) {
+    throw refusePasskey(ceremony, 'credential-owner');
+  }
+  const verified = await verifyAssertion(policy, envelope, credential.publicKey);
+  if (!verified.ok) throw refusePasskey(ceremony, verified.check);
+  const assertion = verified.value;
+  if (assertion.userHandle !== null && assertion.userHandle !== credential.userId) {
+    throw refusePasskey(ceremony, 'user-handle');
+  }
+  // §7.2 step 21: a counter that did not move forward means two devices hold this key. Both
+  // zero is an authenticator that keeps no counter (most synced passkeys), which is allowed.
+  const counted = assertion.signCount !== 0 || credential.signCount !== 0;
+  if (counted && assertion.signCount <= credential.signCount) {
+    logger.warn('auth.passkey.counter_regressed', {
+      credentialId: credential.id,
+      stored: credential.signCount,
+      presented: assertion.signCount,
+    });
+    throw refusePasskey(ceremony, 'counter');
+  }
+  const advanced = await auth.adapter.advancePasskeyCounter(
+    credential.id,
+    credential.signCount,
+    assertion.signCount,
+    auth.clock.now(),
+  );
+  // Lost the compare-and-set: another assertion on this counter value landed first.
+  if (!advanced) throw refusePasskey(ceremony, 'counter-race');
+  return { credential, assertion };
+}

package/src/passkey-challenge.ts

@@ -0,0 +1,59 @@
+// Single responsibility: a ceremony challenge's life — minted from the CSPRNG (or, for a step-up,
+// derived from a nonce and the server's digest), stored as its sha256 with a TTL through the
+// adapter, and redeemed ONCE by the hash `clientDataJSON` echoes. Never a process-local map: a
+// fleet answers the options on one replica and the response on another.
+
+import type { PasskeyCeremony, PasskeyChallengeRecord } from './adapter';
+import type { Auth } from './auth';
+import { base64Url } from './base64url';
+import { passkeyChallengeExpired } from './passkey-errors';
+import { randomBytes, sha256Hex } from './tokens';
+
+export interface IssuedChallenge {
+  /** The base64url challenge to put in the options. */
+  readonly challenge: string;
+}
+
+export interface ChallengeBinding {
+  readonly userId: string | null;
+  readonly digest?: string | undefined;
+  readonly nonce?: string | undefined;
+  /** A step-up's derived challenge; omitted, 32 random bytes are drawn. */
+  readonly challenge?: Uint8Array | undefined;
+  readonly ttlMs: number;
+}
+
+export async function issuePasskeyChallenge(
+  auth: Auth,
+  ceremony: PasskeyCeremony,
+  binding: ChallengeBinding,
+): Promise<IssuedChallenge> {
+  const challenge = base64Url(binding.challenge ?? randomBytes(32));
+  const now = auth.clock.now();
+  await auth.adapter.putPasskeyChallenge({
+    id: sha256Hex(challenge),
+    ceremony,
+    userId: binding.userId,
+    digest: binding.digest ?? null,
+    nonce: binding.nonce ?? null,
+    expiresAt: new Date(now.getTime() + binding.ttlMs),
+    createdAt: now,
+  });
+  return { challenge };
+}
+
+/**
+ * Consumed first, judged second: an expired row is gone either way, and a replay of a redeemed
+ * one finds nothing. Unknown, spent and late are ONE refusal — which it was is not the caller's.
+ */
+export async function redeemPasskeyChallenge(
+  auth: Auth,
+  ceremony: PasskeyCeremony,
+  challenge: string,
+): Promise<PasskeyChallengeRecord> {
+  const row = await auth.adapter.takePasskeyChallenge(sha256Hex(challenge), ceremony);
+  if (row === null || row.expiresAt.getTime() <= auth.clock.now().getTime()) {
+    throw passkeyChallengeExpired(ceremony);
+  }
+  return row;
+}

package/src/passkey-client.ts

@@ -0,0 +1,156 @@
+// Single responsibility: the BROWSER half of a passkey ceremony — the server's JSON options into
+// `navigator.credentials.create/get`, and the credential back out as JSON for the app's action.
+// Imports only `base64url.ts` and types, so an island offering "Sign in with a passkey" pays for
+// these lines and nothing of the server package (`@ultimat3/auth/client`, `client-bundle.test.ts`).
+//
+//   const options = await client.passkeyLoginOptions({});
+//   const outcome = await getPasskey(options);
+//   if (outcome.status === 'ok') await client.passkeySignIn({ response: outcome.response });
+
+import { base64Url, canonicalBase64UrlBytes } from './base64url';
+import type {
+  PasskeyAssertionResponse,
+  PasskeyCreationOptions,
+  PasskeyCredentialDescriptor,
+  PasskeyRegistrationResponse,
+  PasskeyRequestOptions,
+} from './passkey-wire';
+
+/**
+ * Every branch is an outcome to render, never an exception: `cancelled` is the person's choice
+ * (or the timeout), `unsupported` the browser's, `failed` anything else, named by the DOM error.
+ */
+export type PasskeyOutcome<T> =
+  | { readonly status: 'ok'; readonly response: T }
+  | { readonly status: 'cancelled' }
+  | { readonly status: 'unsupported' }
+  | { readonly status: 'failed'; readonly error: string };
+
+/** The browser surface this touches — injectable, so a test runs a ceremony without a browser. */
+export interface PasskeyClientHost {
+  create(options: CredentialCreationOptions): Promise<Credential | null>;
+  get(options: CredentialRequestOptions): Promise<Credential | null>;
+}
+
+const browserHost = (): PasskeyClientHost | null => {
+  const container = globalThis.navigator?.credentials;
+  return container === undefined || globalThis.PublicKeyCredential === undefined ? null : container;
+};
+
+/** Whether this browser can run a ceremony at all — for hiding the button, not for security. */
+export const passkeysSupported = (): boolean => browserHost() !== null;
+
+const bytes = (field: string): Uint8Array<ArrayBuffer> =>
+  canonicalBase64UrlBytes(field) ?? new Uint8Array();
+
+const TRANSPORTS: ReadonlySet<string> = new Set([
+  'usb',
+  'nfc',
+  'ble',
+  'smart-card',
+  'hybrid',
+  'internal',
+]);
+const isTransport = (value: string): value is AuthenticatorTransport => TRANSPORTS.has(value);
+
+const descriptor = (row: PasskeyCredentialDescriptor): PublicKeyCredentialDescriptor => ({
+  type: 'public-key',
+  id: bytes(row.id),
+  transports: row.transports.filter(isTransport),
+});
+
+const text = (buffer: ArrayBuffer | null | undefined): string =>
+  buffer === null || buffer === undefined ? '' : base64Url(new Uint8Array(buffer));
+
+/** Structural, not `instanceof`: a test host (and a polyfill) has no `PublicKeyCredential` class. */
+const isPublicKey = (credential: Credential | null): credential is PublicKeyCredential =>
+  credential !== null &&
+  credential.type === 'public-key' &&
+  'rawId' in credential &&
+  credential.rawId instanceof ArrayBuffer &&
+  'response' in credential;
+
+const outcomeOf = (error: unknown): PasskeyOutcome<never> => {
+  const name =
+    typeof error === 'object' && error !== null && 'name' in error ? String(error.name) : 'Error';
+  // `NotAllowedError` is what every browser answers for "the person closed the sheet" and for the
+  // timeout alike, deliberately indistinguishable (§13.4.7); `AbortError` is the page's own abort.
+  if (name === 'NotAllowedError' || name === 'AbortError') return { status: 'cancelled' };
+  return { status: 'failed', error: name };
+};
+
+/** Registration: `passkeyLogin(auth).registerOptions` in, `register`'s `response` out. */
+export async function newPasskey(
+  options: PasskeyCreationOptions,
+  host: PasskeyClientHost | null = browserHost(),
+): Promise<PasskeyOutcome<PasskeyRegistrationResponse>> {
+  if (host === null) return { status: 'unsupported' };
+  try {
+    const credential = await host.create({
+      publicKey: {
+        challenge: bytes(options.challenge),
+        rp: options.rp,
+        user: { ...options.user, id: bytes(options.user.id) },
+        pubKeyCredParams: [...options.pubKeyCredParams],
+        timeout: options.timeout,
+        attestation: options.attestation,
+        authenticatorSelection: options.authenticatorSelection,
+        excludeCredentials: options.excludeCredentials.map(descriptor),
+      },
+    });
+    if (!isPublicKey(credential)) return { status: 'failed', error: 'NoCredential' };
+    const response = credential.response as AuthenticatorAttestationResponse;
+    return {
+      status: 'ok',
+      response: {
+        id: credential.id,
+        rawId: text(credential.rawId),
+        type: 'public-key',
+        response: {
+          clientDataJSON: text(response.clientDataJSON),
+          attestationObject: text(response.attestationObject),
+          transports: typeof response.getTransports === 'function' ? response.getTransports() : [],
+        },
+      },
+    };
+  } catch (error) {
+    return outcomeOf(error);
+  }
+}
+
+/** Sign-in and step-up: `loginOptions` / `stepUp.options` in, `login` / `verify`'s `response` out. */
+export async function getPasskey(
+  options: PasskeyRequestOptions,
+  host: PasskeyClientHost | null = browserHost(),
+): Promise<PasskeyOutcome<PasskeyAssertionResponse>> {
+  if (host === null) return { status: 'unsupported' };
+  try {
+    const credential = await host.get({
+      publicKey: {
+        challenge: bytes(options.challenge),
+        rpId: options.rpId,
+        timeout: options.timeout,
+        userVerification: options.userVerification,
+        allowCredentials: options.allowCredentials.map(descriptor),
+      },
+    });
+    if (!isPublicKey(credential)) return { status: 'failed', error: 'NoCredential' };
+    const response = credential.response as AuthenticatorAssertionResponse;
+    return {
+      status: 'ok',
+      response: {
+        id: credential.id,
+        rawId: text(credential.rawId),
+        type: 'public-key',
+        response: {
+          clientDataJSON: text(response.clientDataJSON),
+          authenticatorData: text(response.authenticatorData),
+          signature: text(response.signature),
+          userHandle: response.userHandle === null ? null : text(response.userHandle),
+        },
+      },
+    };
+  } catch (error) {
+    return outcomeOf(error);
+  }
+}