@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-web-authn.d.mts

@@ -0,0 +1,404 @@
+import { ComputedRef, MaybeRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-web-authn.d.ts
+/** User verification requirement of a WebAuthn ceremony. */
+type WebAuthnUserVerification = "required" | "preferred" | "discouraged";
+/** Attestation conveyance preference of a registration ceremony. */
+type WebAuthnAttestation = "none" | "indirect" | "direct" | "enterprise";
+/** Discoverable-credential (resident key) requirement. */
+type WebAuthnResidentKey = "discouraged" | "preferred" | "required";
+/** Authenticator attachment modality. */
+type WebAuthnAuthenticatorAttachment = "platform" | "cross-platform";
+/** Authenticator transport hint. */
+type WebAuthnTransport = "usb" | "nfc" | "ble" | "hybrid" | "internal";
+/** Client hint about the authenticator the relying party expects. */
+type WebAuthnHint = "security-key" | "client-device" | "hybrid";
+/** Credential mediation requirement; `"conditional"` powers passkey autofill. */
+type WebAuthnMediation = "silent" | "optional" | "conditional" | "required";
+/** Credential descriptor in server JSON form. */
+interface PublicKeyCredentialDescriptorJSON {
+  /** Credential type. */
+  readonly type: "public-key";
+  /** Base64url-encoded credential id. */
+  readonly id: string;
+  /** Transports the credential is reachable through. */
+  readonly transports?: readonly WebAuthnTransport[];
+}
+/** Credential descriptor in binary form. */
+interface WebAuthnCredentialDescriptor {
+  /** Credential type. */
+  type: "public-key";
+  /** Raw credential id. */
+  id: Uint8Array<ArrayBuffer>;
+  /** Transports the credential is reachable through. */
+  transports?: WebAuthnTransport[];
+}
+/** Authenticator selection criteria of a registration ceremony. */
+interface WebAuthnAuthenticatorSelection {
+  /** Required attachment modality. */
+  authenticatorAttachment?: WebAuthnAuthenticatorAttachment;
+  /** Discoverable-credential requirement. */
+  residentKey?: WebAuthnResidentKey;
+  /** Legacy discoverable-credential flag. */
+  requireResidentKey?: boolean;
+  /** User verification requirement. */
+  userVerification?: WebAuthnUserVerification;
+}
+/** Relying party entity. */
+interface WebAuthnRelyingParty {
+  /** Relying party id (a registrable domain). */
+  id?: string;
+  /** Human-readable name. */
+  name: string;
+}
+/** Public-key algorithm parameter. */
+interface WebAuthnCredentialParameter {
+  /** Credential type. */
+  type: "public-key";
+  /** COSE algorithm identifier (for example -7 for ES256). */
+  alg: number;
+}
+/** `PublicKeyCredentialCreationOptions` as serialized by a server (binary fields base64url). */
+interface PublicKeyCredentialCreationOptionsJSON {
+  /** Relying party. */
+  readonly rp: Readonly<WebAuthnRelyingParty>;
+  /** User account with a base64url-encoded `id`. */
+  readonly user: {
+    readonly id: string;
+    readonly name: string;
+    readonly displayName: string;
+  };
+  /** Base64url-encoded challenge. */
+  readonly challenge: string;
+  /** Acceptable algorithms in preference order. */
+  readonly pubKeyCredParams: readonly Readonly<WebAuthnCredentialParameter>[];
+  /** Ceremony timeout in milliseconds. */
+  readonly timeout?: number;
+  /** Credentials that must not be re-registered. */
+  readonly excludeCredentials?: readonly PublicKeyCredentialDescriptorJSON[];
+  /** Authenticator selection criteria. */
+  readonly authenticatorSelection?: Readonly<WebAuthnAuthenticatorSelection>;
+  /** Attestation preference. */
+  readonly attestation?: WebAuthnAttestation;
+  /** Authenticator hints. */
+  readonly hints?: readonly WebAuthnHint[];
+  /** Client extension inputs; PRF values are decoded from base64url. */
+  readonly extensions?: Readonly<Record<string, unknown>>;
+}
+/** `PublicKeyCredentialRequestOptions` as serialized by a server (binary fields base64url). */
+interface PublicKeyCredentialRequestOptionsJSON {
+  /** Base64url-encoded challenge. */
+  readonly challenge: string;
+  /** Ceremony timeout in milliseconds. */
+  readonly timeout?: number;
+  /** Relying party id. */
+  readonly rpId?: string;
+  /** Allowed credentials; empty or omitted for discoverable credentials. */
+  readonly allowCredentials?: readonly PublicKeyCredentialDescriptorJSON[];
+  /** User verification requirement. */
+  readonly userVerification?: WebAuthnUserVerification;
+  /** Authenticator hints. */
+  readonly hints?: readonly WebAuthnHint[];
+  /** Client extension inputs; PRF values are decoded from base64url. */
+  readonly extensions?: Readonly<Record<string, unknown>>;
+}
+/** Binary creation options passed to `navigator.credentials.create`. */
+interface WebAuthnCreationInit {
+  /** Relying party. */
+  rp: WebAuthnRelyingParty;
+  /** User account. */
+  user: {
+    id: Uint8Array<ArrayBuffer>;
+    name: string;
+    displayName: string;
+  };
+  /** Challenge bytes. */
+  challenge: Uint8Array<ArrayBuffer>;
+  /** Acceptable algorithms in preference order. */
+  pubKeyCredParams: WebAuthnCredentialParameter[];
+  /** Ceremony timeout in milliseconds. */
+  timeout?: number;
+  /** Credentials that must not be re-registered. */
+  excludeCredentials?: WebAuthnCredentialDescriptor[];
+  /** Authenticator selection criteria. */
+  authenticatorSelection?: WebAuthnAuthenticatorSelection;
+  /** Attestation preference. */
+  attestation?: WebAuthnAttestation;
+  /** Authenticator hints. */
+  hints?: WebAuthnHint[];
+  /** Client extension inputs. */
+  extensions?: Record<string, unknown>;
+}
+/** Binary request options passed to `navigator.credentials.get`. */
+interface WebAuthnRequestInit {
+  /** Challenge bytes. */
+  challenge: Uint8Array<ArrayBuffer>;
+  /** Ceremony timeout in milliseconds. */
+  timeout?: number;
+  /** Relying party id. */
+  rpId?: string;
+  /** Allowed credentials. */
+  allowCredentials?: WebAuthnCredentialDescriptor[];
+  /** User verification requirement. */
+  userVerification?: WebAuthnUserVerification;
+  /** Authenticator hints. */
+  hints?: WebAuthnHint[];
+  /** Client extension inputs. */
+  extensions?: Record<string, unknown>;
+}
+/** Fields shared by every returned `PublicKeyCredential`. */
+interface PublicKeyCredentialLike {
+  /** Base64url credential id. */
+  readonly id: string;
+  /** Raw credential id. */
+  readonly rawId: ArrayBuffer;
+  /** Credential type (`"public-key"`). */
+  readonly type: string;
+  /** Attachment of the authenticator that produced the credential. */
+  readonly authenticatorAttachment?: string | null;
+  /** Client extension outputs. */
+  getClientExtensionResults(): object;
+}
+/** Credential returned by a registration ceremony. */
+interface RegistrationCredentialLike extends PublicKeyCredentialLike {
+  /** Attestation response. */
+  readonly response: {
+    /** Client data. */readonly clientDataJSON: ArrayBuffer; /** CBOR attestation object. */
+    readonly attestationObject: ArrayBuffer; /** Transports reported by the authenticator. */
+    getTransports?(): readonly string[]; /** DER SubjectPublicKeyInfo of the new credential. */
+    getPublicKey?(): ArrayBuffer | null; /** COSE algorithm of the new credential. */
+    getPublicKeyAlgorithm?(): number; /** Authenticator data. */
+    getAuthenticatorData?(): ArrayBuffer;
+  };
+}
+/** Credential returned by an authentication ceremony. */
+interface AuthenticationCredentialLike extends PublicKeyCredentialLike {
+  /** Assertion response. */
+  readonly response: {
+    /** Client data. */readonly clientDataJSON: ArrayBuffer; /** Authenticator data. */
+    readonly authenticatorData: ArrayBuffer; /** Assertion signature. */
+    readonly signature: ArrayBuffer; /** User handle of a discoverable credential. */
+    readonly userHandle: ArrayBuffer | null;
+  };
+}
+/** JSON-safe registration result, ready to POST to a server. */
+interface RegistrationResponseJSON {
+  /** Base64url credential id. */
+  readonly id: string;
+  /** Base64url raw credential id. */
+  readonly rawId: string;
+  /** Credential type. */
+  readonly type: "public-key";
+  /** Authenticator attachment, when known. */
+  readonly authenticatorAttachment?: WebAuthnAuthenticatorAttachment;
+  /** Client extension outputs. */
+  readonly clientExtensionResults: object;
+  /** Attestation response with base64url fields. */
+  readonly response: {
+    /** Base64url client data. */readonly clientDataJSON: string; /** Base64url attestation object. */
+    readonly attestationObject: string; /** Known transports. */
+    readonly transports?: readonly WebAuthnTransport[]; /** Base64url public key, when exposed. */
+    readonly publicKey?: string; /** COSE algorithm, when exposed. */
+    readonly publicKeyAlgorithm?: number; /** Base64url authenticator data, when exposed. */
+    readonly authenticatorData?: string;
+  };
+}
+/** JSON-safe authentication result, ready to POST to a server. */
+interface AuthenticationResponseJSON {
+  /** Base64url credential id. */
+  readonly id: string;
+  /** Base64url raw credential id. */
+  readonly rawId: string;
+  /** Credential type. */
+  readonly type: "public-key";
+  /** Authenticator attachment, when known. */
+  readonly authenticatorAttachment?: WebAuthnAuthenticatorAttachment;
+  /** Client extension outputs. */
+  readonly clientExtensionResults: object;
+  /** Assertion response with base64url fields. */
+  readonly response: {
+    /** Base64url client data. */readonly clientDataJSON: string; /** Base64url authenticator data. */
+    readonly authenticatorData: string; /** Base64url signature. */
+    readonly signature: string; /** Base64url user handle, when present. */
+    readonly userHandle?: string;
+  };
+}
+/** Minimal `navigator.credentials` consumed by {@link useWebAuthn}. */
+interface WebAuthnCredentialsHost {
+  /** Run a registration ceremony. */
+  create(options: {
+    publicKey: WebAuthnCreationInit;
+    signal?: AbortSignal;
+    mediation?: WebAuthnMediation;
+  }): Promise<unknown>;
+  /** Run an authentication ceremony. */
+  get(options: {
+    publicKey: WebAuthnRequestInit;
+    signal?: AbortSignal;
+    mediation?: WebAuthnMediation;
+  }): Promise<unknown>;
+}
+/** Static capability checks of `PublicKeyCredential`. */
+interface PublicKeyCredentialStatics {
+  /** Whether a user-verifying platform authenticator (Touch ID, Windows Hello) exists. */
+  isUserVerifyingPlatformAuthenticatorAvailable?(): Promise<boolean>;
+  /** Whether conditional mediation (passkey autofill) is available. */
+  isConditionalMediationAvailable?(): Promise<boolean>;
+}
+/** Options for {@link useWebAuthn}. */
+interface UseWebAuthnOptions {
+  /**
+   * Credentials container for alternate runtimes and tests.
+   *
+   * @default window.navigator.credentials when `window.PublicKeyCredential` exists
+   */
+  readonly credentials?: MaybeRefOrGetter<WebAuthnCredentialsHost | null | undefined>;
+  /**
+   * `PublicKeyCredential` interface used for capability checks. A ref (not a
+   * getter) because the browser value is a constructor function.
+   *
+   * @default window.PublicKeyCredential
+   */
+  readonly publicKeyCredential?: MaybeRef<PublicKeyCredentialStatics | null | undefined>;
+}
+/** Per-ceremony options of {@link WebAuthnControls.create} and {@link WebAuthnControls.get}. */
+interface WebAuthnCeremonyOptions {
+  /**
+   * Mediation requirement; `"conditional"` for passkey autofill.
+   *
+   * @default undefined
+   */
+  readonly mediation?: WebAuthnMediation;
+  /**
+   * Additional signal aborting the ceremony.
+   *
+   * @default undefined
+   */
+  readonly signal?: AbortSignal;
+}
+/** Discriminated outcome of a WebAuthn ceremony. */
+type WebAuthnResult<Credential> = {
+  /** The ceremony produced a credential. */readonly status: "success"; /** Returned credential. */
+  readonly credential: Credential;
+} | {
+  /**
+   * `aborted`: aborted by `abort()`, a newer ceremony, or `signal`;
+   * `not-allowed`: the user cancelled or the ceremony timed out;
+   * `unsupported`: WebAuthn is unavailable; `failed`: anything else.
+   */
+  readonly status: "aborted" | "not-allowed" | "unsupported" | "failed"; /** Error thrown by the host, when one was thrown. */
+  readonly error: unknown;
+};
+/** Reactive state and actions returned by {@link useWebAuthn}. */
+interface WebAuthnControls {
+  /** Whether WebAuthn is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Whether a ceremony is in progress. */
+  readonly pending: Readonly<Ref<boolean>>;
+  /** Most recent ceremony failure (not aborts), cleared when a ceremony starts. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Register a credential. Aborts any pending ceremony first.
+   *
+   * @param options Binary options or server JSON (parsed automatically).
+   * @param ceremony Mediation and extra abort signal.
+   * @returns The discriminated outcome; never rejects.
+   */
+  readonly create: (options: WebAuthnCreationInit | PublicKeyCredentialCreationOptionsJSON, ceremony?: WebAuthnCeremonyOptions) => Promise<WebAuthnResult<RegistrationCredentialLike>>;
+  /**
+   * Authenticate with a credential. Aborts any pending ceremony first.
+   *
+   * @param options Binary options or server JSON (parsed automatically).
+   * @param ceremony Mediation (for example `"conditional"`) and extra abort signal.
+   * @returns The discriminated outcome; never rejects.
+   */
+  readonly get: (options: WebAuthnRequestInit | PublicKeyCredentialRequestOptionsJSON, ceremony?: WebAuthnCeremonyOptions) => Promise<WebAuthnResult<AuthenticationCredentialLike>>;
+  /**
+   * Abort the pending ceremony, if any.
+   *
+   * @param reason Abort reason.
+   */
+  readonly abort: (reason?: unknown) => void;
+  /**
+   * Whether a user-verifying platform authenticator exists.
+   *
+   * @returns `false` when unsupported or the check fails.
+   */
+  readonly isUserVerifyingPlatformAuthenticatorAvailable: () => Promise<boolean>;
+  /**
+   * Whether conditional mediation (passkey autofill) is available.
+   *
+   * @returns `false` when unsupported or the check fails.
+   */
+  readonly isConditionalMediationAvailable: () => Promise<boolean>;
+}
+/**
+ * Encode bytes as unpadded base64url.
+ *
+ * @param bytes Buffer or view to encode.
+ * @returns Base64url text without `=` padding.
+ */
+declare function encodeBase64Url(bytes: ArrayBuffer | ArrayBufferView): string;
+/**
+ * Decode base64url (padded or unpadded) into bytes.
+ *
+ * @param text Base64url text.
+ * @throws `TypeError` tagged `VIZE_COMPOSE_WEBAUTHN_INVALID_BASE64URL` for malformed input.
+ * @returns Decoded bytes.
+ */
+declare function decodeBase64Url(text: string): Uint8Array<ArrayBuffer>;
+/**
+ * Convert server creation-options JSON into binary options for `create`.
+ *
+ * @param json Options with base64url `challenge`, `user.id`, and credential ids.
+ * @throws `TypeError` tagged `VIZE_COMPOSE_WEBAUTHN_INVALID_BASE64URL` for malformed fields.
+ * @returns Binary creation options.
+ */
+declare function parseCreationOptionsFromJSON(json: PublicKeyCredentialCreationOptionsJSON): WebAuthnCreationInit;
+/**
+ * Convert server request-options JSON into binary options for `get`.
+ *
+ * @param json Options with base64url `challenge` and credential ids.
+ * @throws `TypeError` tagged `VIZE_COMPOSE_WEBAUTHN_INVALID_BASE64URL` for malformed fields.
+ * @returns Binary request options.
+ */
+declare function parseRequestOptionsFromJSON(json: PublicKeyCredentialRequestOptionsJSON): WebAuthnRequestInit;
+/**
+ * Serialize a registration credential into JSON-safe base64url fields.
+ *
+ * @param credential Credential resolved by `create`.
+ * @returns Server-ready registration response.
+ */
+declare function serializeRegistrationCredential(credential: RegistrationCredentialLike): RegistrationResponseJSON;
+/**
+ * Serialize an authentication credential into JSON-safe base64url fields.
+ *
+ * @param credential Credential resolved by `get`.
+ * @returns Server-ready authentication response.
+ */
+declare function serializeAuthenticationCredential(credential: AuthenticationCredentialLike): AuthenticationResponseJSON;
+/**
+ * Register and authenticate passkeys with the Web Authentication API.
+ *
+ * `create` and `get` accept binary options or server JSON, run one ceremony
+ * at a time (starting one aborts the previous), and resolve to a
+ * discriminated {@link WebAuthnResult}. Use the exported pure helpers to
+ * serialize results for the server. A pending ceremony is aborted when the
+ * owning reactive scope stops; outside a scope call `abort()`.
+ *
+ * Server rendering: nothing is requested, `supported` and `pending` are false.
+ *
+ * @example
+ * ```ts
+ * const webAuthn = useWebAuthn();
+ * const result = await webAuthn.get(await fetchJSON("/login/options"));
+ * if (result.status === "success") await post(serializeAuthenticationCredential(result.credential));
+ * ```
+ *
+ * @param options Capability hosts.
+ * @default options {}
+ * @returns Ceremony state and actions.
+ */
+declare function useWebAuthn(options?: UseWebAuthnOptions): WebAuthnControls;
+//#endregion
+export { AuthenticationCredentialLike, AuthenticationResponseJSON, PublicKeyCredentialCreationOptionsJSON, PublicKeyCredentialDescriptorJSON, PublicKeyCredentialLike, PublicKeyCredentialRequestOptionsJSON, PublicKeyCredentialStatics, RegistrationCredentialLike, RegistrationResponseJSON, UseWebAuthnOptions, WebAuthnAttestation, WebAuthnAuthenticatorAttachment, WebAuthnAuthenticatorSelection, WebAuthnCeremonyOptions, WebAuthnControls, WebAuthnCreationInit, WebAuthnCredentialDescriptor, WebAuthnCredentialParameter, WebAuthnCredentialsHost, WebAuthnHint, WebAuthnMediation, WebAuthnRelyingParty, WebAuthnRequestInit, WebAuthnResidentKey, WebAuthnResult, WebAuthnTransport, WebAuthnUserVerification, decodeBase64Url, encodeBase64Url, parseCreationOptionsFromJSON, parseRequestOptionsFromJSON, serializeAuthenticationCredential, serializeRegistrationCredential, useWebAuthn };