@udibo/oauth2 0.41.0 → 0.43.0

package/README.md

@@ -164,6 +164,7 @@ and examples in the [reference](https://jsr.io/@udibo/oauth2/doc).
 | `/hono/bff`                  | BFF routes, server-held tokens, session and pending-login stores                                |
 | `/identity`                  | App-owned signup, login, password reset, email verification, passwordless, and protection hooks |
 | `/identity/mfa`              | TOTP, recovery codes, and MFA storage contract                                                  |
+| `/identity/passkeys`         | Passkey (WebAuthn) registration and sign-in, as a first or second factor                        |
 | `/identity/external`         | Social and external OIDC sign-in for your own login pages                                       |
 | `/identity/migration`        | Verify imported password hashes and upgrade them at login                                       |
 | `/hono/identity`             | Hono routes for `IdentityService`                                                               |

package/dist/errors.d.ts

@@ -159,6 +159,11 @@ export declare const InsufficientPermissionsError: OAuth2ErrorClass;
  * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
  */
 export declare const UnsupportedResponseTypeError: OAuth2ErrorClass;
+/**
+ * The requested resource is missing, malformed or not allowed by the server's
+ * resource policy (RFC 8707 section 2). Descriptions should not echo targets.
+ */
+export declare const InvalidTargetError: OAuth2ErrorClass;
 /**
  * The requested scope is invalid, unknown, or malformed.
  *

package/dist/errors.js

@@ -205,6 +205,15 @@ export const UnsupportedResponseTypeError = createHttpErrorClass({
         error: "unsupported_response_type",
     },
 });
+/**
+ * The requested resource is missing, malformed or not allowed by the server's
+ * resource policy (RFC 8707 section 2). Descriptions should not echo targets.
+ */
+export const InvalidTargetError = createHttpErrorClass({
+    name: "Invalid Target",
+    status: 400,
+    extensions: { error: "invalid_target" },
+});
 /**
  * The requested scope is invalid, unknown, or malformed.
  *

package/dist/identity/errors.d.ts

@@ -7,13 +7,13 @@
  */
 /**
  * Stable, machine-readable identity error codes. The package raises
- * `rate_limited`, `weak_password`, and the `mfa_*` codes, and the Hono route
+ * `rate_limited`, `weak_password`, and the `mfa_*` and `passkey_*` codes, and the Hono route
  * factory answers `forbidden_origin` (its same-origin guard, before a handler
  * runs) and `invalid_credentials` / `invalid_token` (a failed sign-in or token
  * check); the rest are for your store and routes to throw (e.g. `identifier_taken` on
  * a duplicate sign-up, `captcha_failed` after `verifyCaptcha`).
  */
-export type IdentityErrorCode = "invalid_credentials" | "invalid_token" | "rate_limited" | "weak_password" | "identifier_taken" | "email_not_verified" | "mfa_not_enrolled" | "mfa_already_enrolled" | "captcha_failed" | "forbidden_origin";
+export type IdentityErrorCode = "invalid_credentials" | "invalid_token" | "rate_limited" | "weak_password" | "identifier_taken" | "email_not_verified" | "mfa_not_enrolled" | "mfa_already_enrolled" | "passkey_limit_reached" | "passkey_not_registered" | "captcha_failed" | "forbidden_origin";
 /** Options for {@link IdentityError}. */
 export interface IdentityErrorOptions extends ErrorOptions {
     /** For `rate_limited`: milliseconds until the caller may retry. */

package/dist/identity/errors.js

@@ -40,6 +40,8 @@ const STATUS = {
     email_not_verified: 403,
     mfa_not_enrolled: 409,
     mfa_already_enrolled: 409,
+    passkey_limit_reached: 409,
+    passkey_not_registered: 409,
     captcha_failed: 403,
     forbidden_origin: 403,
 };

package/dist/identity/events.d.ts

@@ -4,7 +4,8 @@
  * {@link IdentityService} emits an {@link IdentityEvent} after each significant
  * auth outcome (sign-in success/failure, sign-up, credential upgrade-on-login,
  * reset and verification lifecycle, passwordless sign-in links and codes),
- * `MfaService` emits the `mfa.*` events, and a password-policy validator emits
+ * `MfaService` emits the `mfa.*` events, `PasskeyService` the `passkey.*`
+ * events, and a password-policy validator emits
  * `password_policy.check_unavailable` when it cannot complete its check. Wire
  * an {@link IdentityEventHook} via the service's `onEvent`
  * option to persist them in your own audit store — storage stays app-owned,
@@ -34,7 +35,8 @@ export type SignInFailureReason = "unknown_identifier" | "no_password" | "wrong_
  */
 export type SignInCodeFailureReason = "invalid" | "expired" | "locked" | "unknown_email";
 /**
- * An auth outcome emitted by {@link IdentityService}, `MfaService`, or a
+ * An auth outcome emitted by {@link IdentityService}, `MfaService`,
+ * `PasskeyService`, or a
  * password-policy validator. Discriminated on `type`; `userId` is present when
  * the flow resolved an account.
  */
@@ -251,6 +253,46 @@ export type IdentityEvent = {
 } | {
     type: "mfa.disabled";
     userId: string;
+} | {
+    type: "passkey.registered";
+    userId: string;
+    credentialId: string;
+    /** Whether the passkey may sync between devices. */
+    multiDevice: boolean;
+} | {
+    type: "passkey.registration.failed";
+    userId: string;
+    reason: "expired_challenge" | "invalid" | "duplicate" | "limit_reached";
+} | {
+    type: "passkey.verify.succeeded";
+    userId: string;
+    credentialId: string;
+    /** Whether the authenticator verified the person (PIN or biometric). */
+    userVerified: boolean;
+} | {
+    type: "passkey.verify.failed";
+    /**
+     * `"sign_count"` means the authenticator's counter went backwards — a
+     * possible cloned authenticator, worth an alert.
+     */
+    reason: "expired_challenge" | "unknown_passkey" | "invalid" | "sign_count" | "replayed";
+    /** Present when the passkey resolved to an account. */
+    userId?: string;
+    credentialId?: string;
+} | {
+    type: "passkey.verify.rate_limited";
+    userId?: string;
+    credentialId?: string;
+    retryAfterMs: number;
+    enforced: boolean;
+} | {
+    type: "passkey.renamed";
+    userId: string;
+    credentialId: string;
+} | {
+    type: "passkey.removed";
+    userId: string;
+    credentialId: string;
 };
 /**
  * Receives each {@link IdentityEvent} after the flow's outcome is decided. The

package/dist/identity/events.js

@@ -4,7 +4,8 @@
  * {@link IdentityService} emits an {@link IdentityEvent} after each significant
  * auth outcome (sign-in success/failure, sign-up, credential upgrade-on-login,
  * reset and verification lifecycle, passwordless sign-in links and codes),
- * `MfaService` emits the `mfa.*` events, and a password-policy validator emits
+ * `MfaService` emits the `mfa.*` events, `PasskeyService` the `passkey.*`
+ * events, and a password-policy validator emits
  * `password_policy.check_unavailable` when it cannot complete its check. Wire
  * an {@link IdentityEventHook} via the service's `onEvent`
  * option to persist them in your own audit store — storage stays app-owned,

package/dist/identity/passkeys/mod.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Passkeys (WebAuthn) for apps that own their login: registration and
+ * sign-in ceremonies over app-owned stores, usable as a first factor and as a
+ * second factor. Verification is delegated to `@simplewebauthn/server`; this
+ * module applies a consumer-friendly policy on top:
+ *
+ * - **No attestation.** Any passkey manager, platform, or FIDO2 security key
+ *   works; nothing is allow-listed by authenticator model.
+ * - **Discoverable credentials**, so a person can sign in without typing an
+ *   identifier, and sign-in without a known user lists no credentials and so
+ *   reveals nothing about which accounts exist.
+ * - **User verification preferred and reported**, so the app decides whether a
+ *   passkey alone satisfies its MFA policy.
+ * - **Single-use challenges**, a per-user cap (25 by default), sign-count clone
+ *   detection, rate limiting, and `passkey.*` events.
+ *
+ * - {@link PasskeyService} — `startRegistration` / `finishRegistration`,
+ *   `startAuthentication` / `finishAuthentication`, and list, rename, remove.
+ * - {@link PasskeyStore} and {@link PasskeyChallengeStore} — the app's
+ *   persistence seams, with {@link MemoryPasskeyStore} and
+ *   {@link MemoryPasskeyChallengeStore} for development and tests.
+ * - {@link PASSKEY_AMR} — the `amr` value a passkey contributes.
+ *
+ * The browser side is `navigator.credentials.create()` / `.get()` with the
+ * returned options; `@simplewebauthn/browser` or the native
+ * `PublicKeyCredential.parseCreationOptionsFromJSON` handle the conversion.
+ * `TestPasskeyAuthenticator` in `@udibo/oauth2/testing` produces real
+ * responses for tests.
+ *
+ * @example Serve a passkey sign-in
+ * ```ts
+ * import {
+ *   MemoryPasskeyChallengeStore,
+ *   MemoryPasskeyStore,
+ *   PasskeyService,
+ * } from "@udibo/oauth2/identity/passkeys";
+ *
+ * const passkeys = new PasskeyService({
+ *   store: new MemoryPasskeyStore(),
+ *   challenges: new MemoryPasskeyChallengeStore(),
+ * });
+ * const relyingParty = {
+ *   id: "login.example.com",
+ *   name: "Example",
+ *   origins: ["https://login.example.com"],
+ * };
+ * const { ceremonyId, options } = await passkeys.startAuthentication({
+ *   relyingParty,
+ * });
+ * // set ceremonyId in an HttpOnly cookie and send options to the browser
+ * ```
+ *
+ * @module
+ */
+export { type FinishPasskeyAuthenticationOptions, type FinishPasskeyRegistrationOptions, MemoryPasskeyChallengeStore, MemoryPasskeyStore, type Passkey, PASSKEY_AMR, type PasskeyAddResult, type PasskeyAuthenticationOptions, type PasskeyAuthenticationResponse, type PasskeyCeremony, type PasskeyChallenge, type PasskeyChallengeStore, type PasskeyRegistration, type PasskeyRegistrationFailureReason, type PasskeyRegistrationOptions, type PasskeyRegistrationResponse, type PasskeyRelyingParty, PasskeyService, type PasskeyServiceOptions, type PasskeyStore, type PasskeyUse, type PasskeyUser, type PasskeyVerification, type PasskeyVerifyFailureReason, type StartPasskeyAuthenticationOptions, type StartPasskeyRegistrationOptions, } from "./service.ts";

package/dist/identity/passkeys/mod.js

@@ -0,0 +1,55 @@
+/**
+ * Passkeys (WebAuthn) for apps that own their login: registration and
+ * sign-in ceremonies over app-owned stores, usable as a first factor and as a
+ * second factor. Verification is delegated to `@simplewebauthn/server`; this
+ * module applies a consumer-friendly policy on top:
+ *
+ * - **No attestation.** Any passkey manager, platform, or FIDO2 security key
+ *   works; nothing is allow-listed by authenticator model.
+ * - **Discoverable credentials**, so a person can sign in without typing an
+ *   identifier, and sign-in without a known user lists no credentials and so
+ *   reveals nothing about which accounts exist.
+ * - **User verification preferred and reported**, so the app decides whether a
+ *   passkey alone satisfies its MFA policy.
+ * - **Single-use challenges**, a per-user cap (25 by default), sign-count clone
+ *   detection, rate limiting, and `passkey.*` events.
+ *
+ * - {@link PasskeyService} — `startRegistration` / `finishRegistration`,
+ *   `startAuthentication` / `finishAuthentication`, and list, rename, remove.
+ * - {@link PasskeyStore} and {@link PasskeyChallengeStore} — the app's
+ *   persistence seams, with {@link MemoryPasskeyStore} and
+ *   {@link MemoryPasskeyChallengeStore} for development and tests.
+ * - {@link PASSKEY_AMR} — the `amr` value a passkey contributes.
+ *
+ * The browser side is `navigator.credentials.create()` / `.get()` with the
+ * returned options; `@simplewebauthn/browser` or the native
+ * `PublicKeyCredential.parseCreationOptionsFromJSON` handle the conversion.
+ * `TestPasskeyAuthenticator` in `@udibo/oauth2/testing` produces real
+ * responses for tests.
+ *
+ * @example Serve a passkey sign-in
+ * ```ts
+ * import {
+ *   MemoryPasskeyChallengeStore,
+ *   MemoryPasskeyStore,
+ *   PasskeyService,
+ * } from "@udibo/oauth2/identity/passkeys";
+ *
+ * const passkeys = new PasskeyService({
+ *   store: new MemoryPasskeyStore(),
+ *   challenges: new MemoryPasskeyChallengeStore(),
+ * });
+ * const relyingParty = {
+ *   id: "login.example.com",
+ *   name: "Example",
+ *   origins: ["https://login.example.com"],
+ * };
+ * const { ceremonyId, options } = await passkeys.startAuthentication({
+ *   relyingParty,
+ * });
+ * // set ceremonyId in an HttpOnly cookie and send options to the browser
+ * ```
+ *
+ * @module
+ */
+export { MemoryPasskeyChallengeStore, MemoryPasskeyStore, PASSKEY_AMR, PasskeyService, } from "./service.js";