@smartcrab/browser 0.1.0

package/dist/errors.js

@@ -0,0 +1,44 @@
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Narrows an already-JSON-parsed body to the Problem Details shape. Field
+ * types are checked one by one; extension members are ignored (carried by the
+ * server for its own diagnostics, not part of the client contract).
+ */
+export const parseProblemDetailsWire = (value) => {
+    if (!isPlainObject(value))
+        return null;
+    if (typeof value["type"] !== "string" || typeof value["title"] !== "string")
+        return null;
+    if (typeof value["status"] !== "number" || !Number.isInteger(value["status"]))
+        return null;
+    const detail = value["detail"];
+    const code = value["code"];
+    const requestId = value["request_id"];
+    if (detail !== undefined && typeof detail !== "string")
+        return null;
+    if (code !== undefined && typeof code !== "string")
+        return null;
+    if (requestId !== undefined && typeof requestId !== "string")
+        return null;
+    return {
+        type: value["type"],
+        title: value["title"],
+        status: value["status"],
+        ...(detail !== undefined ? { detail } : {}),
+        ...(code !== undefined ? { code } : {}),
+        ...(requestId !== undefined ? { requestId } : {}),
+    };
+};
+export const parseOAuthErrorWire = (value) => {
+    if (!isPlainObject(value))
+        return null;
+    if (typeof value["error"] !== "string" || value["error"].length === 0)
+        return null;
+    const description = value["error_description"];
+    if (description !== undefined && typeof description !== "string")
+        return null;
+    return {
+        error: value["error"],
+        ...(description !== undefined ? { description } : {}),
+    };
+};

package/dist/http.d.ts

@@ -0,0 +1,49 @@
+import type { Outcome } from "@smartcrab/contracts-public";
+import type { OAuthErrorCode } from "@smartcrab/contracts-public";
+import type { BrowserAuthError } from "./errors.js";
+/**
+ * HTTP transport for the public API (design.md §16.2) and the token endpoint
+ * (design.md §15.1).
+ *
+ * Responsibilities:
+ * - exact request serialization (JSON bodies, Bearer header, query strings)
+ * - response normalization into `BrowserAuthError` (network failure, 429 with
+ *   `Retry-After`, RFC 9457 Problem Details, RFC 6749 OAuth errors, and
+ *   `invalid_response` for anything that does not match the wire contract)
+ * - success-path validation through the contracts-public zod schemas — the
+ *   wire is never trusted (IMPL_NOTES §1)
+ *
+ * Exception boundaries are promise rejection handlers (`.then(onOk, onErr)`),
+ * never `try`/`catch` statements: `scripts/check-backend-error-style.ts`
+ * (design.md §5.2) scans this package and rejects direct try-catch.
+ */
+/** Minimal structural view of a zod schema's `safeParse` (this package has no zod dependency). */
+export interface WireSchema<T> {
+    safeParse(input: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: unknown;
+    };
+}
+export type FetchPort = (url: string, init: RequestInit) => Promise<Response>;
+export type HttpMethod = "GET" | "POST" | "PATCH" | "DELETE";
+export interface JsonRequest {
+    readonly method: HttpMethod;
+    /** Fully-built URL, including query string. */
+    readonly url: string;
+    readonly body?: unknown;
+    readonly accessToken?: string;
+}
+export declare const isOAuthErrorCode: (value: string) => value is OAuthErrorCode;
+/**
+ * Executes one JSON request and validates the response against `schema`.
+ *
+ * Error precedence on non-2xx: 429 → `rate_limited`; a valid Problem Details
+ * body → `problem_details`; a valid OAuth error body → `oauth_error`;
+ * anything else → `invalid_response`.
+ */
+export declare const requestJson: <T>(fetchPort: FetchPort, request: JsonRequest, schema: WireSchema<T>) => Promise<Outcome<T, BrowserAuthError>>;
+/** Builds `base + path` plus an optional query string. */
+export declare const buildUrl: (baseUrl: string, path: string, query?: Record<string, string>) => string;

package/dist/http.js

@@ -0,0 +1,113 @@
+import { err, ok } from "@smartcrab/contracts-public";
+import { OAUTH_ERROR_CODES } from "@smartcrab/contracts-public";
+import { parseOAuthErrorWire, parseProblemDetailsWire } from "./errors.js";
+const OAUTH_ERROR_CODE_SET = new Set(OAUTH_ERROR_CODES);
+export const isOAuthErrorCode = (value) => OAUTH_ERROR_CODE_SET.has(value);
+const parseRetryAfterSeconds = (response) => {
+    const raw = response.headers.get("retry-after");
+    if (raw === null)
+        return undefined;
+    // Only the delta-seconds form is honored; HTTP-date form is intentionally
+    // unsupported (the platform always emits delta-seconds).
+    if (!/^[0-9]+$/.test(raw.trim()))
+        return undefined;
+    return Number.parseInt(raw.trim(), 10);
+};
+const invalidResponse = (message, status) => err({
+    type: "invalid_response",
+    message,
+    ...(status !== undefined ? { status } : {}),
+});
+const toNetworkError = (cause) => err({
+    type: "network_error",
+    message: cause instanceof Error ? cause.message : "Network request failed",
+    retryable: true,
+});
+/** `JSON.parse` without a try statement: the throw becomes a rejection inside the promise chain. */
+const parseJsonBody = (text, status) => Promise.resolve()
+    .then(() => JSON.parse(text))
+    .then((value) => ok(value), () => invalidResponse("Response body was not valid JSON", status));
+/**
+ * Executes one JSON request and validates the response against `schema`.
+ *
+ * Error precedence on non-2xx: 429 → `rate_limited`; a valid Problem Details
+ * body → `problem_details`; a valid OAuth error body → `oauth_error`;
+ * anything else → `invalid_response`.
+ */
+export const requestJson = async (fetchPort, request, schema) => {
+    const headers = {
+        accept: "application/json",
+        ...(request.body !== undefined ? { "content-type": "application/json" } : {}),
+        ...(request.accessToken !== undefined
+            ? { authorization: `Bearer ${request.accessToken}` }
+            : {}),
+    };
+    const responseOutcome = await fetchPort(request.url, {
+        method: request.method,
+        headers,
+        ...(request.body !== undefined ? { body: JSON.stringify(request.body) } : {}),
+    }).then((response) => ok(response), toNetworkError);
+    if (!responseOutcome.ok)
+        return responseOutcome;
+    const response = responseOutcome.value;
+    // A rejection while streaming the body is still a transport failure.
+    const textOutcome = await response
+        .text()
+        .then((text) => ok(text), toNetworkError);
+    if (!textOutcome.ok)
+        return textOutcome;
+    const text = textOutcome.value;
+    const jsonOutcome = text.length === 0 ? ok(undefined) : await parseJsonBody(text, response.status);
+    if (!jsonOutcome.ok)
+        return jsonOutcome;
+    const json = jsonOutcome.value;
+    if (response.status === 429) {
+        const retryAfterSeconds = parseRetryAfterSeconds(response);
+        const problem = parseProblemDetailsWire(json);
+        return err({
+            type: "rate_limited",
+            retryable: true,
+            ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}),
+            ...(problem !== null && problem.requestId !== undefined
+                ? { requestId: problem.requestId }
+                : {}),
+        });
+    }
+    if (!response.ok) {
+        const problem = parseProblemDetailsWire(json);
+        if (problem !== null) {
+            return err({
+                type: "problem_details",
+                problemType: problem.type,
+                code: problem.code ?? "unknown_error",
+                title: problem.title,
+                status: problem.status,
+                ...(problem.detail !== undefined ? { detail: problem.detail } : {}),
+                ...(problem.requestId !== undefined ? { requestId: problem.requestId } : {}),
+            });
+        }
+        const oauthError = parseOAuthErrorWire(json);
+        if (oauthError !== null && isOAuthErrorCode(oauthError.error)) {
+            return err({
+                type: "oauth_error",
+                code: oauthError.error,
+                status: response.status,
+                ...(oauthError.description !== undefined ? { description: oauthError.description } : {}),
+            });
+        }
+        return invalidResponse(`HTTP ${response.status} error body was neither Problem Details nor an OAuth error`, response.status);
+    }
+    const parsed = schema.safeParse(json);
+    if (!parsed.success) {
+        return invalidResponse("Response body did not match the public API contract", response.status);
+    }
+    return ok(parsed.data);
+};
+/** Builds `base + path` plus an optional query string. */
+export const buildUrl = (baseUrl, path, query) => {
+    const url = `${baseUrl}${path}`;
+    if (query === undefined || Object.keys(query).length === 0)
+        return url;
+    const params = new URLSearchParams(query);
+    return `${url}?${params.toString()}`;
+};

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @smartcrab/browser — dependency-free SPA client for the passwordless
+ * auth platform's public API (design.md §16 transaction API, §15 token
+ * endpoint, §22.3 SPA rules).
+ *
+ * - Every request/response goes through the `@smartcrab/contracts-public`
+ *   zod schemas; malformed wire data surfaces as typed `invalid_response`
+ *   failures, never as trusted objects.
+ * - Access tokens live in memory only (design.md §22.3); refresh-token
+ *   persistence is an explicit, documented opt-in.
+ * - Fallible methods return `Outcome<T, BrowserAuthError>` — the local
+ *   discriminated-union channel from contracts-public, because
+ *   `@praha/byethrow` is not resolvable from this package (not a declared
+ *   dependency).
+ */
+export { createBrowserAuthClient } from "./client.js";
+export type { AuthenticatedSession, BrowserAuthClient, BrowserAuthClientConfig, BrowserAuthListener, BrowserAuthSnapshot, BrowserTransaction, CreateTransactionInput, HostedAuthorization, RedirectPort, RefreshTokenStoragePort, } from "./client.js";
+export { parseOAuthErrorWire, parseProblemDetailsWire } from "./errors.js";
+export type { BrowserAuthError, InvalidResponseError, NetworkFailureError, NotAuthenticatedError, OAuthErrorWire, OAuthFailureError, ProblemDetailsError, ProblemDetailsWire, RateLimitedError, StateMismatchError, WebAuthnFailureError, WebAuthnFailureReason, } from "./errors.js";
+export { buildUrl, requestJson } from "./http.js";
+export type { FetchPort, HttpMethod, JsonRequest, WireSchema } from "./http.js";
+export { generateNonce, generatePkcePair, generateState } from "./pkce.js";
+export type { PkcePair } from "./pkce.js";
+export { base64UrlDecodeToBytes, base64UrlEncodeBytes, bufferToBase64Url } from "./base64url.js";
+export { navigatorWebAuthnPort } from "./webauthn.js";
+export type { WebAuthnBrowserPort } from "./webauthn.js";
+export { err, ok } from "@smartcrab/contracts-public";
+export type { EmailChallengeResponse, MeIdentitySummary, MeSessionSummary, MeUpdateRequest, MeUser, Outcome, PasskeySummary, PublicConfigResponse, SocialProvider, TransactionStatus, } from "@smartcrab/contracts-public";

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * @smartcrab/browser — dependency-free SPA client for the passwordless
+ * auth platform's public API (design.md §16 transaction API, §15 token
+ * endpoint, §22.3 SPA rules).
+ *
+ * - Every request/response goes through the `@smartcrab/contracts-public`
+ *   zod schemas; malformed wire data surfaces as typed `invalid_response`
+ *   failures, never as trusted objects.
+ * - Access tokens live in memory only (design.md §22.3); refresh-token
+ *   persistence is an explicit, documented opt-in.
+ * - Fallible methods return `Outcome<T, BrowserAuthError>` — the local
+ *   discriminated-union channel from contracts-public, because
+ *   `@praha/byethrow` is not resolvable from this package (not a declared
+ *   dependency).
+ */
+export { createBrowserAuthClient } from "./client.js";
+export { parseOAuthErrorWire, parseProblemDetailsWire } from "./errors.js";
+export { buildUrl, requestJson } from "./http.js";
+export { generateNonce, generatePkcePair, generateState } from "./pkce.js";
+export { base64UrlDecodeToBytes, base64UrlEncodeBytes, bufferToBase64Url } from "./base64url.js";
+export { navigatorWebAuthnPort } from "./webauthn.js";
+// Selected contract types re-exported so downstream SDKs (e.g.
+// `@smartcrab/react`, which cannot depend on contracts-public directly)
+// can type their own surfaces against the exact wire shapes. `ok`/`err` are
+// re-exported as values so consumers can construct `Outcome`s themselves.
+export { err, ok } from "@smartcrab/contracts-public";

package/dist/pkce.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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";
+}
+/**
+ * Transaction `state` (design.md §16.1: the server stores only a MAC of it).
+ * 256 bits of entropy, base64url — opaque to the server.
+ */
+export declare const generateState: () => string;
+/** OIDC `nonce` for ID token replay protection (design.md §32.1). */
+export declare const generateNonce: () => string;
+/** Generates a verifier/challenge pair; `plain` is never offered (design.md §15.3). */
+export declare const generatePkcePair: () => Promise<PkcePair>;

package/dist/pkce.js

@@ -0,0 +1,21 @@
+import { base64UrlEncodeBytes } from "./base64url.js";
+const randomBase64Url = (byteLength) => {
+    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 = () => randomBase64Url(32);
+/** OIDC `nonce` for ID token replay protection (design.md §32.1). */
+export const generateNonce = () => randomBase64Url(32);
+/** Generates a verifier/challenge pair; `plain` is never offered (design.md §15.3). */
+export const generatePkcePair = async () => {
+    // 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/dist/webauthn.d.ts

@@ -0,0 +1,26 @@
+import type { PasskeyAuthenticationCredential, PasskeyAuthenticationOptionsResponse, PasskeyRegistrationCredential, PasskeyRegistrationOptionsResponse } from "@smartcrab/contracts-public";
+import type { Outcome } from "@smartcrab/contracts-public";
+import type { WebAuthnFailureError } 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>>;
+}
+/** Default port: the browser's own platform authenticator via `navigator.credentials`. */
+export declare const navigatorWebAuthnPort: WebAuthnBrowserPort;

package/dist/webauthn.js

@@ -0,0 +1,214 @@
+import { err, ok } from "@smartcrab/contracts-public";
+import { base64UrlDecodeToBytes, bufferToBase64Url } from "./base64url.js";
+const failure = (reason, message) => err({ type: "webauthn_error", reason, message });
+const NOT_SUPPORTED = 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) => {
+    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 };
+};
+const AUTHENTICATOR_TRANSPORTS = ["ble", "hybrid", "internal", "nfc", "usb"];
+const isTransport = (value) => AUTHENTICATOR_TRANSPORTS.includes(value);
+/** `getTransports()` is Level 3; older engines lack it, hence the feature detection. */
+const readTransports = (candidate) => {
+    if (typeof candidate.getTransports !== "function")
+        return undefined;
+    const raw = candidate.getTransports();
+    if (!Array.isArray(raw))
+        return undefined;
+    const transports = raw
+        .filter((entry) => typeof entry === "string")
+        .filter(isTransport);
+    return transports.length > 0 ? transports : undefined;
+};
+const isPublicKeyCredential = (credential) => credential.type === "public-key" && "rawId" in credential && "response" in credential;
+const isAttestationResponse = (response) => "attestationObject" in response;
+const isAssertionResponse = (response) => "authenticatorData" in response && "signature" in response;
+const toBufferSource = (base64url) => {
+    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) => {
+    const results = credential.getClientExtensionResults();
+    const entries = Object.entries(results);
+    if (entries.length === 0)
+        return undefined;
+    const out = {};
+    for (const [key, value] of entries) {
+        out[key] = value;
+    }
+    return out;
+};
+const toAttachment = (value) => value === "platform" ? "platform" : "cross-platform";
+const serializeRegistrationCredential = (credential) => {
+    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) => {
+    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 = () => typeof navigator !== "undefined" &&
+    typeof navigator.credentials !== "undefined" &&
+    typeof PublicKeyCredential !== "undefined";
+const toCreationOptions = (options) => ({
+    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) => ({
+    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) => {
+    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), (cause) => err(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) => {
+    if (!isWebAuthnSupported())
+        return NOT_SUPPORTED;
+    const credentialOutcome = await Promise.resolve()
+        .then(() => toRequestOptions(options))
+        .then((publicKey) => navigator.credentials.get({ publicKey }))
+        .then((credential) => ok(credential), (cause) => err(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 = {
+    isAvailable: isWebAuthnSupported,
+    create,
+    get,
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@smartcrab/browser",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./src/*.ts",
+      "development": "./src/*.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@smartcrab/contracts-public": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "build": "tsc -p tsconfig.build.json"
+  }
+}

package/src/base64url.ts

@@ -0,0 +1,47 @@
+/**
+ * Local base64url (RFC 4648 §5, no padding) helpers.
+ *
+ * Duplicated intentionally from `@smartcrab/identifiers` rather than
+ * imported: that package is not a dependency of this SDK (only
+ * `@smartcrab/contracts-public` is), and adding it just for ~40 lines of
+ * alphabet math would widen the published dependency surface for no
+ * behavioral gain. Implementations are byte-for-byte compatible.
+ */
+
+const BASE64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+export const base64UrlEncodeBytes = (bytes: Uint8Array): string => {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i] ?? 0;
+    const b1 = bytes[i + 1];
+    const b2 = bytes[i + 2];
+    out += BASE64URL_ALPHABET[b0 >> 2] ?? "";
+    out += BASE64URL_ALPHABET[((b0 & 0x03) << 4) | ((b1 ?? 0) >> 4)] ?? "";
+    if (b1 !== undefined) out += BASE64URL_ALPHABET[((b1 & 0x0f) << 2) | ((b2 ?? 0) >> 6)] ?? "";
+    if (b2 !== undefined) out += BASE64URL_ALPHABET[b2 & 0x3f] ?? "";
+  }
+  return out;
+};
+
+export const base64UrlDecodeToBytes = (encoded: string): Uint8Array => {
+  const out: number[] = [];
+  let buffer = 0;
+  let bits = 0;
+  for (const char of encoded) {
+    const index = BASE64URL_ALPHABET.indexOf(char);
+    if (index < 0) {
+      throw new Error(`Invalid base64url character: ${char}`);
+    }
+    buffer = (buffer << 6) | index;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out.push((buffer >>> bits) & 0xff);
+    }
+  }
+  return new Uint8Array(out);
+};
+
+export const bufferToBase64Url = (buffer: ArrayBuffer): string =>
+  base64UrlEncodeBytes(new Uint8Array(buffer));