@structured-id/ui-core 4.8.0 → 4.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structured-id/ui-core",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "type": "module",
   "publishConfig": {
     "access": "public",

package/src/index.ts

@@ -54,6 +54,10 @@ export {
   formatRelativeTime,
   truncate,
   maskEmail,
+  PasskeyError,
+  createPasskey,
+  getPasskey,
+  type PasskeyFailure,
 } from "./utils";
 
 export {

package/src/utils/index.ts

@@ -20,6 +20,13 @@ export {
   type EmailPolicy,
 } from "./email";
 
+export {
+  PasskeyError,
+  createPasskey,
+  getPasskey,
+  type PasskeyFailure,
+} from "./passkey";
+
 export {
   formatDate,
   formatRelativeTime,

package/src/utils/passkey.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { PasskeyError, createPasskey, getPasskey } from "./passkey";
+
+const bytes = (value: unknown) =>
+  new TextEncoder().encode(JSON.stringify(value));
+const json = (data: Uint8Array) =>
+  JSON.parse(new TextDecoder().decode(data)) as Record<string, unknown>;
+
+/** A browser credential whose JSON form is `form`. */
+class FakeCredential {
+  constructor(private readonly form: unknown) {}
+  toJSON() {
+    return this.form;
+  }
+}
+
+const parseCreation = vi.fn((options: unknown) => ({ parsed: options }));
+const parseRequest = vi.fn((options: unknown) => ({ parsed: options }));
+const create = vi.fn();
+const get = vi.fn();
+
+beforeEach(() => {
+  Object.assign(FakeCredential, {
+    parseCreationOptionsFromJSON: parseCreation,
+    parseRequestOptionsFromJSON: parseRequest,
+  });
+  vi.stubGlobal("PublicKeyCredential", FakeCredential);
+  vi.stubGlobal("navigator", { credentials: { create, get } });
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.clearAllMocks();
+});
+
+// The JSON the server reads is the browser's own form, clientExtensionResults
+// included: SID's relying party refuses a response without that member
+// (WebAuthn Level 3 §5.1.4), which hand-built responses left out.
+const REGISTRATION = {
+  id: "Y3JlZA",
+  rawId: "Y3JlZA",
+  type: "public-key",
+  response: { clientDataJSON: "e30", attestationObject: "o2M" },
+  clientExtensionResults: {},
+};
+
+describe("passkey creation", () => {
+  // The server wraps the options in `publicKey` (CredentialCreationOptions);
+  // reading members off the top level parsed nothing.
+  it("hands the browser the options inside publicKey", async () => {
+    create.mockResolvedValue(new FakeCredential(REGISTRATION));
+    const publicKey = { challenge: "Y2g", rp: { id: "sid.example.com" } };
+    const response = await createPasskey(bytes({ publicKey }));
+    expect(parseCreation).toHaveBeenCalledWith(publicKey);
+    expect(create).toHaveBeenCalledWith({ publicKey: { parsed: publicKey } });
+    expect(json(response)).toEqual(REGISTRATION);
+  });
+
+  it("tells a cancellation and a known authenticator apart", async () => {
+    const options = bytes({ publicKey: { challenge: "Y2g" } });
+    create.mockRejectedValue(new DOMException("no", "NotAllowedError"));
+    await expect(createPasskey(options)).rejects.toMatchObject({
+      failure: "cancelled",
+    });
+    create.mockRejectedValue(new DOMException("held", "InvalidStateError"));
+    await expect(createPasskey(options)).rejects.toMatchObject({
+      failure: "already-registered",
+    });
+    create.mockRejectedValue(new Error("broken"));
+    await expect(createPasskey(options)).rejects.toMatchObject({
+      failure: "failed",
+      message: "broken",
+    });
+  });
+
+  it("refuses options without publicKey and a missing credential", async () => {
+    await expect(
+      createPasskey(bytes({ challenge: "Y2g" })),
+    ).rejects.toBeInstanceOf(PasskeyError);
+    create.mockResolvedValue(null);
+    await expect(
+      createPasskey(bytes({ publicKey: { challenge: "Y2g" } })),
+    ).rejects.toMatchObject({ failure: "failed" });
+  });
+});
+
+describe("passkey assertion", () => {
+  const ASSERTION = {
+    id: "Y3JlZA",
+    rawId: "Y3JlZA",
+    type: "public-key",
+    response: {
+      clientDataJSON: "e30",
+      authenticatorData: "YXV0aA",
+      signature: "c2ln",
+      userHandle: "dXNlcg",
+    },
+    clientExtensionResults: {},
+  };
+
+  it("answers the request options with the browser's JSON form", async () => {
+    get.mockResolvedValue(new FakeCredential(ASSERTION));
+    const publicKey = { challenge: "Y2g", rpId: "sid.example.com" };
+    const response = await getPasskey(bytes({ publicKey }));
+    expect(parseRequest).toHaveBeenCalledWith(publicKey);
+    expect(get).toHaveBeenCalledWith({ publicKey: { parsed: publicKey } });
+    expect(json(response)).toEqual(ASSERTION);
+  });
+
+  it("reports a cancelled sign-in as cancelled", async () => {
+    get.mockRejectedValue(new DOMException("no", "NotAllowedError"));
+    await expect(
+      getPasskey(bytes({ publicKey: { challenge: "Y2g" } })),
+    ).rejects.toMatchObject({ failure: "cancelled" });
+  });
+});

package/src/utils/passkey.ts

@@ -0,0 +1,107 @@
+/**
+ * The browser side of SID's passkey ceremonies, whatever transport carries
+ * them: the options a start returns (`CredentialCreationOptions` /
+ * `CredentialRequestOptions` as JSON, `publicKey` inside) in, the
+ * `RegistrationResponseJSON` / `AuthenticationResponseJSON` a finish reads
+ * out (WebAuthn Level 3 §5.1.4), on the browser's own JSON forms.
+ */
+
+/** How a ceremony ended without a credential. */
+export type PasskeyFailure =
+  /** The user cancelled, or the authenticator timed out (`NotAllowedError`). */
+  | "cancelled"
+  /** The authenticator already holds a passkey of this account (`InvalidStateError`). */
+  | "already-registered"
+  /** Anything else, the browser's message kept in `cause`. */
+  | "failed";
+
+/** A ceremony that produced no credential, and why. */
+export class PasskeyError extends Error {
+  constructor(
+    readonly failure: PasskeyFailure,
+    message: string,
+    options?: { cause?: unknown },
+  ) {
+    super(message, options);
+    this.name = "PasskeyError";
+  }
+}
+
+/** The `publicKey` member of the options JSON the server sent. */
+function publicKeyOf<T>(options: Uint8Array): T {
+  const parsed = JSON.parse(new TextDecoder().decode(options)) as {
+    publicKey?: T;
+  };
+  if (!parsed.publicKey) {
+    throw new PasskeyError("failed", "The server sent no passkey options");
+  }
+  return parsed.publicKey;
+}
+
+/** Why the browser refused, as the page tells it. */
+function refusal(error: unknown): PasskeyError {
+  if (error instanceof DOMException && error.name === "NotAllowedError") {
+    return new PasskeyError(
+      "cancelled",
+      "The request was cancelled or timed out",
+      {
+        cause: error,
+      },
+    );
+  }
+  if (error instanceof DOMException && error.name === "InvalidStateError") {
+    return new PasskeyError(
+      "already-registered",
+      "This authenticator already holds a passkey for this account",
+      { cause: error },
+    );
+  }
+  return new PasskeyError(
+    "failed",
+    error instanceof Error ? error.message : "The passkey ceremony failed",
+    { cause: error },
+  );
+}
+
+/** `credential` as the JSON bytes a finish reads. */
+function responseBytes(credential: Credential | null): Uint8Array {
+  if (!(credential instanceof PublicKeyCredential)) {
+    throw new PasskeyError("failed", "The browser returned no passkey");
+  }
+  return new TextEncoder().encode(JSON.stringify(credential.toJSON()));
+}
+
+/**
+ * Create a passkey from a registration start's `options`; resolves to the
+ * response a registration finish takes.
+ */
+export async function createPasskey(options: Uint8Array): Promise<Uint8Array> {
+  const publicKey = PublicKeyCredential.parseCreationOptionsFromJSON(
+    publicKeyOf<PublicKeyCredentialCreationOptionsJSON>(options),
+  );
+  let credential: Credential | null;
+  try {
+    credential = await navigator.credentials.create({ publicKey });
+  } catch (error) {
+    throw refusal(error);
+  }
+  return responseBytes(credential);
+}
+
+/**
+ * Assert a passkey for a sign-in or step-up start's `options`; resolves to
+ * the response its finish takes. With no allowed credentials in `options`
+ * the browser offers the discoverable passkeys it holds for the RP.
+ */
+export async function getPasskey(options: Uint8Array): Promise<Uint8Array> {
+  const publicKey = PublicKeyCredential.parseRequestOptionsFromJSON(
+    publicKeyOf<PublicKeyCredentialRequestOptionsJSON>(options),
+  );
+  let credential: Credential | null;
+  try {
+    credential = await navigator.credentials.get({ publicKey });
+  } catch (error) {
+    throw refusal(error);
+  }
+  return responseBytes(credential);
+}