@structured-id/ui-core 4.8.0 → 4.10.0

package/package.json

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

package/src/composables/operationKey.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect, vi } from "vitest";
+import type { MethodInfo, RpcOptions } from "@protobuf-ts/runtime-rpc";
+import { OPERATION_KEY, operationKey } from "./operationKey";
+
+/** The options a unary call reaches the transport with. */
+function sent(
+  idempotency: MethodInfo["idempotency"],
+  options: RpcOptions = {},
+) {
+  const next = vi.fn((_m, _i, o: RpcOptions) => o);
+  const method = { idempotency } as unknown as MethodInfo;
+  operationKey.interceptUnary!(next as never, method, {}, options);
+  return next.mock.calls[0][2] as RpcOptions;
+}
+
+describe("operationKey", () => {
+  // A state-changing call is named by a key, so SID can answer its retry
+  // with the recorded result instead of applying it again.
+  it("adds a key to a call that changes state", () => {
+    expect(sent(undefined).meta?.[OPERATION_KEY]).toMatch(/^[0-9a-f-]{36}$/);
+    expect(sent("IDEMPOTENT").meta?.[OPERATION_KEY]).toMatch(/^[0-9a-f-]{36}$/);
+  });
+
+  it("adds no key to a read", () => {
+    expect(sent("NO_SIDE_EFFECTS").meta?.[OPERATION_KEY]).toBeUndefined();
+  });
+
+  // A caller retrying one command passes the same key every time.
+  it("keeps a key the caller passed", () => {
+    const options = { meta: { [OPERATION_KEY]: "mine", other: "x" } };
+    expect(sent(undefined, options).meta).toEqual(options.meta);
+  });
+
+  it("gives every call its own key", () => {
+    expect(sent(undefined).meta?.[OPERATION_KEY]).not.toBe(
+      sent(undefined).meta?.[OPERATION_KEY],
+    );
+  });
+});

package/src/composables/operationKey.ts

@@ -0,0 +1,40 @@
+/**
+ * The operation key of state-changing calls: SID answers a retried command
+ * with its recorded result only when the call names it by a key the caller
+ * created before sending it.
+ */
+import type { RpcInterceptor, RpcOptions } from "@protobuf-ts/runtime-rpc";
+
+/** The metadata entry carrying the key (the `Idempotency-Key` header). */
+export const OPERATION_KEY = "idempotency-key";
+
+/**
+ * `options` with an operation key: the caller's own when it passed one (a
+ * caller retrying one command passes the same key every time), a new one
+ * otherwise.
+ */
+export function withOperationKey(options: RpcOptions): RpcOptions {
+  if (options.meta?.[OPERATION_KEY]) {
+    return options;
+  }
+  return {
+    ...options,
+    meta: { ...options.meta, [OPERATION_KEY]: crypto.randomUUID() },
+  };
+}
+
+/**
+ * Adds an operation key to every unary call of a method not declared free of
+ * side effects; reads carry none.
+ */
+export const operationKey: RpcInterceptor = {
+  interceptUnary(next, method, input, options) {
+    return next(
+      method,
+      input,
+      method.idempotency === "NO_SIDE_EFFECTS"
+        ? options
+        : withOperationKey(options),
+    );
+  },
+};

package/src/composables/useAccountTransport.ts

@@ -10,6 +10,7 @@
 import { GrpcWebFetchTransport } from "@protobuf-ts/grpcweb-transport";
 import type { RpcInterceptor, RpcTransport } from "@protobuf-ts/runtime-rpc";
 import { bffCsrfToken } from "./useBffAuth";
+import { operationKey } from "./operationKey";
 
 /** Where the account API is reached. */
 export interface AccountApiConfig {
@@ -49,7 +50,7 @@ export function initAccountApi(config: AccountApiConfig): void {
     baseUrl: config.baseUrl,
     // The BFF is on this origin; its cookie must not travel anywhere else.
     fetchInit: { credentials: "same-origin" },
-    interceptors: [csrf],
+    interceptors: [csrf, operationKey],
   });
 }
 

package/src/composables/useGrpc.test.ts

@@ -14,6 +14,7 @@ vi.mock("@protobuf-ts/grpcweb-transport", () => ({
 // Import AFTER mocks
 import { GrpcWebFetchTransport } from "@protobuf-ts/grpcweb-transport";
 import { initGrpc, getTransport, closeTransport, useGrpc } from "./useGrpc";
+import { operationKey } from "./operationKey";
 import type { GrpcConfig } from "../types/auth";
 
 // ---------------------------------------------------------------------------
@@ -28,7 +29,7 @@ describe("useGrpc", () => {
 
   describe("initGrpc", () => {
     // The BFF session cookie rides on every call, so credentials are always
-    // included; nothing else configures the transport.
+    // included; state-changing calls carry an operation key.
     it("creates GrpcWebFetchTransport with baseUrl and credentials", () => {
       const config: GrpcConfig = { baseUrl: "https://api.sid.example.com" };
       initGrpc(config);
@@ -36,6 +37,7 @@ describe("useGrpc", () => {
       expect(GrpcWebFetchTransport).toHaveBeenCalledWith({
         baseUrl: "https://api.sid.example.com",
         fetchInit: { credentials: "include" },
+        interceptors: [operationKey],
       });
     });
   });

package/src/composables/useGrpc.ts

@@ -2,6 +2,7 @@ import { GrpcWebFetchTransport } from "@protobuf-ts/grpcweb-transport";
 import type { RpcTransport } from "@protobuf-ts/runtime-rpc";
 import { ref, type Ref } from "vue";
 import type { GrpcConfig } from "../types/auth";
+import { operationKey } from "./operationKey";
 
 /** Shared gRPC-web transport instance. */
 let _transport: RpcTransport | null = null;
@@ -23,6 +24,7 @@ export function initGrpc(config: GrpcConfig): void {
     // The BFF proxy exchanges the session cookie for a Bearer token
     // server-side.
     fetchInit: { credentials: "include" },
+    interceptors: [operationKey],
   });
 }
 

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);
+}