@smartcrab/browser 0.1.0

package/src/pkce.ts

@@ -0,0 +1,43 @@
+import { base64UrlEncodeBytes } from "./base64url.js";
+
+/**
+ * PKCE (RFC 7636) and anti-replay value generation for the SPA flow
+ * (design.md §22.3, §32.1: Authorization Code + PKCE S256, state/nonce 必須).
+ *
+ * Uses the bare `crypto` WebCrypto global only (`crypto.getRandomValues`,
+ * `crypto.subtle.digest`) — never `globalThis.crypto`, never Node builtins —
+ * so the module works identically in browsers and Workers-like runtimes
+ * (IMPL_NOTES §5).
+ */
+
+export interface PkcePair {
+  /** RFC 7636 §4.1 verifier: 43 chars from 32 random bytes, unreserved charset. */
+  readonly verifier: string;
+  /** RFC 7636 §4.2 S256 challenge: base64url(SHA-256(verifier)), 43 chars. */
+  readonly challenge: string;
+  readonly method: "S256";
+}
+
+const randomBase64Url = (byteLength: number): string => {
+  const bytes = new Uint8Array(byteLength);
+  crypto.getRandomValues(bytes);
+  return base64UrlEncodeBytes(bytes);
+};
+
+/**
+ * Transaction `state` (design.md §16.1: the server stores only a MAC of it).
+ * 256 bits of entropy, base64url — opaque to the server.
+ */
+export const generateState = (): string => randomBase64Url(32);
+
+/** OIDC `nonce` for ID token replay protection (design.md §32.1). */
+export const generateNonce = (): string => randomBase64Url(32);
+
+/** Generates a verifier/challenge pair; `plain` is never offered (design.md §15.3). */
+export const generatePkcePair = async (): Promise<PkcePair> => {
+  // 32 bytes → 43 base64url chars: inside the RFC 7636 §4.1 43–128 window and
+  // matches the contracts-public `codeVerifierSchema` charset exactly.
+  const verifier = randomBase64Url(32);
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return { verifier, challenge: base64UrlEncodeBytes(new Uint8Array(digest)), method: "S256" };
+};

package/src/webauthn.ts

@@ -0,0 +1,295 @@
+import type {
+  PasskeyAuthenticationCredential,
+  PasskeyAuthenticationOptionsResponse,
+  PasskeyRegistrationCredential,
+  PasskeyRegistrationOptionsResponse,
+} from "@smartcrab/contracts-public";
+import { err, ok } from "@smartcrab/contracts-public";
+import type { Outcome } from "@smartcrab/contracts-public";
+import { base64UrlDecodeToBytes, bufferToBase64Url } from "./base64url.js";
+import type { WebAuthnFailureError, WebAuthnFailureReason } from "./errors.js";
+
+/**
+ * WebAuthn ceremony boundary (design.md §17, §22.3).
+ *
+ * `@simplewebauthn/browser` is deliberately NOT a dependency of this SDK: the
+ * surface we need is two `navigator.credentials` calls plus base64url
+ * (de)serialization, so the SDK ships dependency-free behind this minimal
+ * port. Tests and non-standard runtimes inject their own implementation;
+ * production uses `navigatorWebAuthnPort`.
+ *
+ * Exception boundaries are promise rejection handlers, never `try`/`catch`
+ * statements: `scripts/check-backend-error-style.ts` (design.md §5.2) scans
+ * this package and rejects direct try-catch.
+ */
+
+export interface WebAuthnBrowserPort {
+  /** Runtime capability check (design.md §21.2: UI hides passkeys when false). */
+  isAvailable(): boolean;
+  /** `startRegistration`-style ceremony: JSON options in, JSON credential out. */
+  create(
+    options: PasskeyRegistrationOptionsResponse,
+  ): Promise<Outcome<PasskeyRegistrationCredential, WebAuthnFailureError>>;
+  /** `startAuthentication`-style ceremony: JSON options in, JSON assertion out. */
+  get(
+    options: PasskeyAuthenticationOptionsResponse,
+  ): Promise<Outcome<PasskeyAuthenticationCredential, WebAuthnFailureError>>;
+}
+
+const failure = (
+  reason: WebAuthnFailureReason,
+  message: string,
+): Outcome<never, WebAuthnFailureError> => err({ type: "webauthn_error", reason, message });
+
+const NOT_SUPPORTED: Outcome<never, WebAuthnFailureError> = err({
+  type: "webauthn_error",
+  reason: "not_supported",
+  message: "WebAuthn (PublicKeyCredential) is not available in this environment",
+});
+
+/** Normalizes DOMException names from the authenticator into the public error reasons. */
+const mapCeremonyException = (cause: unknown): WebAuthnFailureError => {
+  if (cause instanceof DOMException) {
+    switch (cause.name) {
+      case "NotAllowedError":
+      case "AbortError":
+        // User dismissal or ceremony timeout (WebAuthn Level 3 §6.1).
+        return { type: "webauthn_error", reason: "cancelled", message: cause.message };
+      case "NotSupportedError":
+        return { type: "webauthn_error", reason: "not_supported", message: cause.message };
+      default:
+        return { type: "webauthn_error", reason: "failed", message: cause.message };
+    }
+  }
+  const message = cause instanceof Error ? cause.message : "Unknown WebAuthn failure";
+  return { type: "webauthn_error", reason: "failed", message };
+};
+
+// The WebAuthn standard transport enum (WebAuthn Level 3 §5.8.4); matches the
+// contracts-public transport union member-for-member.
+type Transport = "ble" | "hybrid" | "internal" | "nfc" | "usb";
+
+const AUTHENTICATOR_TRANSPORTS: readonly string[] = ["ble", "hybrid", "internal", "nfc", "usb"];
+
+const isTransport = (value: string): value is Transport => AUTHENTICATOR_TRANSPORTS.includes(value);
+
+/** `getTransports()` is Level 3; older engines lack it, hence the feature detection. */
+const readTransports = (candidate: { getTransports?: unknown }): Transport[] | undefined => {
+  if (typeof candidate.getTransports !== "function") return undefined;
+  const raw: unknown = candidate.getTransports();
+  if (!Array.isArray(raw)) return undefined;
+  const transports = raw
+    .filter((entry): entry is string => typeof entry === "string")
+    .filter(isTransport);
+  return transports.length > 0 ? transports : undefined;
+};
+
+const isPublicKeyCredential = (credential: Credential): credential is PublicKeyCredential =>
+  credential.type === "public-key" && "rawId" in credential && "response" in credential;
+
+const isAttestationResponse = (
+  response: AuthenticatorResponse,
+): response is AuthenticatorAttestationResponse => "attestationObject" in response;
+
+const isAssertionResponse = (
+  response: AuthenticatorResponse,
+): response is AuthenticatorAssertionResponse =>
+  "authenticatorData" in response && "signature" in response;
+
+const toBufferSource = (base64url: string): ArrayBuffer => {
+  const bytes = base64UrlDecodeToBytes(base64url);
+  // Copy into a standalone ArrayBuffer: BufferSource typing requires a
+  // non-shared, non-resizable backing buffer.
+  const buffer = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(buffer).set(bytes);
+  return buffer;
+};
+
+const extensionResults = (credential: PublicKeyCredential): Record<string, unknown> | undefined => {
+  const results = credential.getClientExtensionResults();
+  const entries = Object.entries(results);
+  if (entries.length === 0) return undefined;
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of entries) {
+    out[key] = value;
+  }
+  return out;
+};
+
+const toAttachment = (value: string): "platform" | "cross-platform" =>
+  value === "platform" ? "platform" : "cross-platform";
+
+const serializeRegistrationCredential = (
+  credential: PublicKeyCredential,
+): PasskeyRegistrationCredential | null => {
+  const { response } = credential;
+  if (!isAttestationResponse(response)) return null;
+  const transports = readTransports(response);
+  const publicKey = typeof response.getPublicKey === "function" ? response.getPublicKey() : null;
+  const authenticatorData =
+    typeof response.getAuthenticatorData === "function" ? response.getAuthenticatorData() : null;
+  const publicKeyAlgorithm =
+    typeof response.getPublicKeyAlgorithm === "function"
+      ? response.getPublicKeyAlgorithm()
+      : undefined;
+  const extensions = extensionResults(credential);
+  return {
+    id: credential.id,
+    rawId: bufferToBase64Url(credential.rawId),
+    type: "public-key",
+    response: {
+      clientDataJSON: bufferToBase64Url(response.clientDataJSON),
+      attestationObject: bufferToBase64Url(response.attestationObject),
+      ...(transports !== undefined ? { transports } : {}),
+      ...(publicKeyAlgorithm !== undefined ? { publicKeyAlgorithm } : {}),
+      ...(publicKey !== null ? { publicKey: bufferToBase64Url(publicKey) } : {}),
+      ...(authenticatorData !== null
+        ? { authenticatorData: bufferToBase64Url(authenticatorData) }
+        : {}),
+    },
+    ...(credential.authenticatorAttachment !== null
+      ? { authenticatorAttachment: toAttachment(credential.authenticatorAttachment) }
+      : {}),
+    ...(extensions !== undefined ? { clientExtensionResults: extensions } : {}),
+  };
+};
+
+const serializeAuthenticationCredential = (
+  credential: PublicKeyCredential,
+): PasskeyAuthenticationCredential | null => {
+  const { response } = credential;
+  if (!isAssertionResponse(response)) return null;
+  const extensions = extensionResults(credential);
+  return {
+    id: credential.id,
+    rawId: bufferToBase64Url(credential.rawId),
+    type: "public-key",
+    response: {
+      clientDataJSON: bufferToBase64Url(response.clientDataJSON),
+      authenticatorData: bufferToBase64Url(response.authenticatorData),
+      signature: bufferToBase64Url(response.signature),
+      ...(response.userHandle !== null
+        ? { userHandle: bufferToBase64Url(response.userHandle) }
+        : {}),
+    },
+    ...(credential.authenticatorAttachment !== null
+      ? { authenticatorAttachment: toAttachment(credential.authenticatorAttachment) }
+      : {}),
+    ...(extensions !== undefined ? { clientExtensionResults: extensions } : {}),
+  };
+};
+
+const isWebAuthnSupported = (): boolean =>
+  typeof navigator !== "undefined" &&
+  typeof navigator.credentials !== "undefined" &&
+  typeof PublicKeyCredential !== "undefined";
+
+const toCreationOptions = (
+  options: PasskeyRegistrationOptionsResponse,
+): PublicKeyCredentialCreationOptions => ({
+  rp: { id: options.rp.id, name: options.rp.name },
+  user: {
+    id: toBufferSource(options.user.id),
+    name: options.user.name,
+    displayName: options.user.displayName,
+  },
+  challenge: toBufferSource(options.challenge),
+  pubKeyCredParams: options.pubKeyCredParams.map((param) => ({ type: param.type, alg: param.alg })),
+  ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
+  ...(options.excludeCredentials !== undefined
+    ? {
+        excludeCredentials: options.excludeCredentials.map((descriptor) => ({
+          id: toBufferSource(descriptor.id),
+          type: descriptor.type,
+          ...(descriptor.transports !== undefined
+            ? { transports: descriptor.transports.filter(isTransport) }
+            : {}),
+        })),
+      }
+    : {}),
+  // design.md §17.1: residentKey/userVerification/attestation are fixed by contract.
+  authenticatorSelection: {
+    ...(options.authenticatorSelection.authenticatorAttachment !== undefined
+      ? { authenticatorAttachment: options.authenticatorSelection.authenticatorAttachment }
+      : {}),
+    residentKey: options.authenticatorSelection.residentKey,
+    userVerification: options.authenticatorSelection.userVerification,
+  },
+  attestation: options.attestation,
+});
+
+const toRequestOptions = (
+  options: PasskeyAuthenticationOptionsResponse,
+): PublicKeyCredentialRequestOptions => ({
+  challenge: toBufferSource(options.challenge),
+  ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
+  rpId: options.rpId,
+  ...(options.allowCredentials !== undefined
+    ? {
+        allowCredentials: options.allowCredentials.map((descriptor) => ({
+          id: toBufferSource(descriptor.id),
+          type: descriptor.type,
+          ...(descriptor.transports !== undefined
+            ? { transports: descriptor.transports.filter(isTransport) }
+            : {}),
+        })),
+      }
+    : {}),
+  userVerification: options.userVerification,
+});
+
+const create = async (
+  options: PasskeyRegistrationOptionsResponse,
+): Promise<Outcome<PasskeyRegistrationCredential, WebAuthnFailureError>> => {
+  if (!isWebAuthnSupported()) return NOT_SUPPORTED;
+  // Options building (base64url decode) is synchronous and can throw; running
+  // it inside the promise chain folds that throw into the same rejection
+  // channel as the ceremony itself — no try statement needed.
+  const credentialOutcome = await Promise.resolve()
+    .then(() => toCreationOptions(options))
+    .then((publicKey) => navigator.credentials.create({ publicKey }))
+    .then(
+      (credential) => ok<Credential | null, WebAuthnFailureError>(credential),
+      (cause: unknown) => err<Credential | null, WebAuthnFailureError>(mapCeremonyException(cause)),
+    );
+  if (!credentialOutcome.ok) return credentialOutcome;
+  const credential = credentialOutcome.value;
+  if (credential === null || !isPublicKeyCredential(credential)) {
+    return failure("failed", "navigator.credentials.create returned no PublicKeyCredential");
+  }
+  const serialized = serializeRegistrationCredential(credential);
+  if (serialized === null) {
+    return failure("failed", "Authenticator response was not an attestation response");
+  }
+  return ok(serialized);
+};
+
+const get = async (
+  options: PasskeyAuthenticationOptionsResponse,
+): Promise<Outcome<PasskeyAuthenticationCredential, WebAuthnFailureError>> => {
+  if (!isWebAuthnSupported()) return NOT_SUPPORTED;
+  const credentialOutcome = await Promise.resolve()
+    .then(() => toRequestOptions(options))
+    .then((publicKey) => navigator.credentials.get({ publicKey }))
+    .then(
+      (credential) => ok<Credential | null, WebAuthnFailureError>(credential),
+      (cause: unknown) => err<Credential | null, WebAuthnFailureError>(mapCeremonyException(cause)),
+    );
+  if (!credentialOutcome.ok) return credentialOutcome;
+  const credential = credentialOutcome.value;
+  if (credential === null || !isPublicKeyCredential(credential)) {
+    return failure("failed", "navigator.credentials.get returned no PublicKeyCredential");
+  }
+  const serialized = serializeAuthenticationCredential(credential);
+  if (serialized === null) {
+    return failure("failed", "Authenticator response was not an assertion response");
+  }
+  return ok(serialized);
+};
+
+/** Default port: the browser's own platform authenticator via `navigator.credentials`. */
+export const navigatorWebAuthnPort: WebAuthnBrowserPort = {
+  isAvailable: isWebAuthnSupported,
+  create,
+  get,
+};