@excom/web-authn 0.1.0

package/support/package-meta.json

@@ -0,0 +1,240 @@
+{
+  "shortName": "web-authn",
+  "package": {
+    "name": "@excom/web-authn",
+    "version": "0.1.0",
+    "description": "<web-authn> custom element",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "authenticate": "<section>\n  <web-authn options-url=\"/api/webauthn/authenticate/options\" verify-url=\"/api/webauthn/authenticate/verify\"\n    start-method=\"authenticate\">\n    <form>\n      <label>\n        Username\n        <input name=\"username\" required autocomplete=\"username webauthn\">\n      </label>\n      <button type=\"submit\">Sign in with passkey</button>\n    </form>\n    <output></output>\n  </web-authn>\n  <quark-sheet>\n    web-authn[is-success] {\n      $res: prop(\"provision\").body;\n      output {\n        content: \"verified: #{$res.verified}\";\n      }\n    }\n    web-authn[is-error] output {\n      content: \"Ceremony failed (this mock needs an authenticator).\";\n    }\n  </quark-sheet>\n</section>\n",
+    "register": "<section>\n  <web-authn options-url=\"/api/webauthn/register/options\" verify-url=\"/api/webauthn/register/verify\"\n    start-method=\"register\">\n    <form>\n      <label>\n        Username\n        <input name=\"username\" required autocomplete=\"username\">\n      </label>\n      <button type=\"submit\">Register passkey</button>\n    </form>\n    <output></output>\n  </web-authn>\n  <quark-sheet>\n    web-authn[is-success] {\n      $res: prop(\"provision\").body;\n      output {\n        content: \"verified: #{$res.verified}\";\n      }\n    }\n    web-authn[is-error] output {\n      content: \"Ceremony failed (this mock needs an authenticator).\";\n    }\n  </quark-sheet>\n</section>\n"
+  },
+  "readme": "<h1 id=\"md-web-authn\">web-authn</h1>\n<p>Passkey register / authenticate with HTML. Pair it with Quark to render the result.</p>\n<p><include-content data-demo=\"register\"></include-content> </p>\n<include-content data-language=\"html\"><template>&lt;web-authn start-method=\"register\" options-url=\"/api/registration-options\" verify-url=\"/api/users\"&gt;\n    &lt;form&gt;\n        &lt;button type=\"submit\"&gt;One click sign up!&lt;/button&gt;\n    &lt;/form&gt;\n&lt;/web-authn&gt;</template></include-content>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Provides data</strong> Use Quark to render the verify response</li>\n<li><strong>Full ceremony</strong> Fetches options, runs the browser&#39;s WebAuthn prompt, then verifies — one element</li>\n<li><strong>Register or authenticate</strong> <code>start-method</code> picks the ceremony</li>\n<li><strong>Submit command</strong> <code>--submit</code> starts the ceremony programmatically — for forms outside the DOM subtree, or buttons outside the <code>&lt;form&gt;</code></li>\n<li><strong>Chainable</strong> <code>web-authn-success</code> fires like any <code>{tag}-success</code> event — chain a redirect or next step</li>\n<li><strong>Highly configurable</strong> Headers, credentials, redirect, etc</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<p>Depends on <a href=\"https://simplewebauthn.dev/\"><code>@simplewebauthn/browser</code></a> for the actual WebAuthn calls (<code>startRegistration</code> / <code>startAuthentication</code>). You can use any server-side library to handle the WebAuthn requests, but it is recommended to use the counterpart library, <a href=\"https://simplewebauthn.dev/\"><code>@simplewebauthn/server</code></a>, since they seamlessly understand the same contract.</p>\n<h2 id=\"md-usage\">Usage</h2>\n<include-content data-language=\"html\"><template>&lt;web-authn options-url=\"/api/webauthn/register/options\"\n  verify-url=\"/api/webauthn/register/verify\" start-method=\"register\"&gt;\n  &lt;form&gt;\n    &lt;input name=\"username\" required&gt;\n    &lt;button type=\"submit\"&gt;Register passkey&lt;/button&gt;\n  &lt;/form&gt;\n&lt;/web-authn&gt;</template></include-content>\n<p>On submit: <code>options-url</code> is fetched for ceremony options, the browser&#39;s native passkey prompt runs (<code>@simplewebauthn/browser</code>), and the resulting credential is posted to <code>verify-url</code>. Use <code>start-method=&quot;authenticate&quot;</code> for sign-in instead of registration.</p>\n<p>Hook the lifecycle state with CSS:</p>\n<include-content data-language=\"css\"><template>web-authn[is-loading] { /* show loading spinner */ }\nweb-authn[is-error]::before { content: \"An error occurred.\" }</template></include-content>\n<p>Or Quark:</p>\n<include-content data-language=\"quark\"><template>web-authn[is-success] {\n  $res: prop(\"provision\").body;\n  span { content: $res.verified; }\n}</template></include-content>\n<p>Chain a next step off success the same way you would for any <code>&lt;super-form&gt;</code> or <code>&lt;provider-fetch&gt;</code>:</p>\n<include-content data-language=\"html\"><template>&lt;event-handler listen-for=\"web-authn-success\" fire-event=\"onboarding-step-complete\"&gt;\n  &lt;web-authn options-url=\"/api/webauthn/register/options\"\n    verify-url=\"/api/webauthn/register/verify\" start-method=\"register\"&gt;\n    &lt;form&gt;&lt;input name=\"username\"&gt;&lt;button type=\"submit\"&gt;Register&lt;/button&gt;&lt;/form&gt;\n  &lt;/web-authn&gt;\n&lt;/event-handler&gt;</template></include-content>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-authenticate\">Authenticate</h4>\n<p><include-content data-demo=\"authenticate\"></include-content></p>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-web-authn\">web-authn</h1>\n<p>Passkey register / authenticate with HTML. Pair it with Quark to render the result.</p>\n<p><include-content data-demo=\"register\"></include-content> </p>\n<include-content data-language=\"html\"><template>&lt;web-authn start-method=\"register\" options-url=\"/api/registration-options\" verify-url=\"/api/users\"&gt;\n    &lt;form&gt;\n        &lt;button type=\"submit\"&gt;One click sign up!&lt;/button&gt;\n    &lt;/form&gt;\n&lt;/web-authn&gt;</template></include-content>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Provides data</strong> Use Quark to render the verify response</li>\n<li><strong>Full ceremony</strong> Fetches options, runs the browser&#39;s WebAuthn prompt, then verifies — one element</li>\n<li><strong>Register or authenticate</strong> <code>start-method</code> picks the ceremony</li>\n<li><strong>Submit command</strong> <code>--submit</code> starts the ceremony programmatically — for forms outside the DOM subtree, or buttons outside the <code>&lt;form&gt;</code></li>\n<li><strong>Chainable</strong> <code>web-authn-success</code> fires like any <code>{tag}-success</code> event — chain a redirect or next step</li>\n<li><strong>Highly configurable</strong> Headers, credentials, redirect, etc</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<p>Depends on <a href=\"https://simplewebauthn.dev/\"><code>@simplewebauthn/browser</code></a> for the actual WebAuthn calls (<code>startRegistration</code> / <code>startAuthentication</code>). You can use any server-side library to handle the WebAuthn requests, but it is recommended to use the counterpart library, <a href=\"https://simplewebauthn.dev/\"><code>@simplewebauthn/server</code></a>, since they seamlessly understand the same contract.</p>\n<h2 id=\"md-usage\">Usage</h2>\n<include-content data-language=\"html\"><template>&lt;web-authn options-url=\"/api/webauthn/register/options\"\n  verify-url=\"/api/webauthn/register/verify\" start-method=\"register\"&gt;\n  &lt;form&gt;\n    &lt;input name=\"username\" required&gt;\n    &lt;button type=\"submit\"&gt;Register passkey&lt;/button&gt;\n  &lt;/form&gt;\n&lt;/web-authn&gt;</template></include-content>\n<p>On submit: <code>options-url</code> is fetched for ceremony options, the browser&#39;s native passkey prompt runs (<code>@simplewebauthn/browser</code>), and the resulting credential is posted to <code>verify-url</code>. Use <code>start-method=&quot;authenticate&quot;</code> for sign-in instead of registration.</p>\n<p>Hook the lifecycle state with CSS:</p>\n<include-content data-language=\"css\"><template>web-authn[is-loading] { /* show loading spinner */ }\nweb-authn[is-error]::before { content: \"An error occurred.\" }</template></include-content>\n<p>Or Quark:</p>\n<include-content data-language=\"quark\"><template>web-authn[is-success] {\n  $res: prop(\"provision\").body;\n  span { content: $res.verified; }\n}</template></include-content>\n<p>Chain a next step off success the same way you would for any <code>&lt;super-form&gt;</code> or <code>&lt;provider-fetch&gt;</code>:</p>\n<include-content data-language=\"html\"><template>&lt;event-handler listen-for=\"web-authn-success\" fire-event=\"onboarding-step-complete\"&gt;\n  &lt;web-authn options-url=\"/api/webauthn/register/options\"\n    verify-url=\"/api/webauthn/register/verify\" start-method=\"register\"&gt;\n    &lt;form&gt;&lt;input name=\"username\"&gt;&lt;button type=\"submit\"&gt;Register&lt;/button&gt;&lt;/form&gt;\n  &lt;/web-authn&gt;\n&lt;/event-handler&gt;</template></include-content>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-authenticate\">Authenticate</h4>\n<p><include-content data-demo=\"authenticate\"></include-content></p>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n"
+  },
+  "installation": {
+    "name": "@excom/web-authn",
+    "shortName": "web-authn",
+    "version": "0.1.0",
+    "description": "<web-authn> custom element",
+    "packageType": "kit-element",
+    "cdn": "<script src=\"https://unpkg.com/@excom/kit-utils/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/neutron/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/web-authn@0.1.0/dist/index.umd.min.js\"></script>",
+    "install": {
+      "npm": "npm install @excom/web-authn"
+    },
+    "imports": {
+      "js": "import \"@excom/web-authn\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/web-authn\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/web-authn\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "web-authn",
+      "summary": "Passkey register / authenticate wired to a <code>&lt;form&gt;</code>.",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "api-method",
+          "type": "string",
+          "description": "HTTP method. Always uppercased before the request is sent.",
+          "fieldName": "apiMethod",
+          "surface": "option",
+          "default": "\"GET\"",
+          "inheritedFrom": "@excom/fetchable-element"
+        },
+        {
+          "name": "api-url",
+          "type": "string",
+          "description": "Endpoint URL. When the request has no body, the JSON payload (from <code>form-ref</code> or custom <code>doFetch()</code> args) is merged in as query params instead.",
+          "fieldName": "apiUrl",
+          "surface": "option",
+          "default": "\"\"",
+          "inheritedFrom": "@excom/fetchable-element"
+        },
+        {
+          "name": "fetch-credentials",
+          "type": "string",
+          "description": "<code>RequestInit.credentials</code> mode.",
+          "fieldName": "fetchCredentials",
+          "surface": "option",
+          "default": "\"include\"",
+          "values": "\"omit\" | \"same-origin\" | \"include\"",
+          "inheritedFrom": "@excom/fetchable-element"
+        },
+        {
+          "name": "fetch-redirect",
+          "type": "string",
+          "description": "<code>RequestInit.redirect</code> mode. Unset defers to the browser default (<code>follow</code>).",
+          "fieldName": "fetchRedirect",
+          "surface": "option",
+          "values": "\"follow\" | \"error\" | \"manual\"",
+          "inheritedFrom": "@excom/fetchable-element"
+        },
+        {
+          "name": "form-ref",
+          "type": "string",
+          "description": "CSS selector for the <code>&lt;form&gt;</code> to intercept. Must be a descendant to be heard directly — point elsewhere and invoke the <code>--submit</code> command instead.",
+          "fieldName": "formRef",
+          "surface": "option",
+          "default": "\":scope form\"",
+          "values": "<CSS Selector>"
+        },
+        {
+          "name": "form-ref",
+          "type": "string",
+          "description": "CSS selector for a <code>&lt;form&gt;</code> to source the request from — its <code>action</code> (URL), <code>method</code>, <code>enctype</code> (Content-Type), and field values (as the JSON payload) all take priority over the matching attributes below. Omit to build the request entirely from attributes / custom <code>doFetch()</code> args.",
+          "fieldName": "formRef",
+          "surface": "option",
+          "values": "<CSS Selector>",
+          "inheritedFrom": "@excom/fetchable-element"
+        },
+        {
+          "name": "has-body",
+          "type": "boolean",
+          "description": "Force a request body even for methods that don&#39;t imply one (<code>GET</code> / <code>HEAD</code>). Already implied for <code>POST</code> / <code>PUT</code> / <code>PATCH</code>.",
+          "fieldName": "hasBody",
+          "surface": "option",
+          "inheritedFrom": "@excom/fetchable-element"
+        },
+        {
+          "name": "header-accept",
+          "type": "string",
+          "description": "<code>Accept</code> request header.",
+          "fieldName": "headerAccept",
+          "surface": "option",
+          "default": "\"application/json\"",
+          "inheritedFrom": "@excom/fetchable-element"
+        },
+        {
+          "name": "header-cache-control",
+          "type": "string",
+          "description": "<code>Cache-Control</code> request header. Unset by default (browser default caching applies).",
+          "fieldName": "headerCacheControl",
+          "surface": "option",
+          "inheritedFrom": "@excom/fetchable-element"
+        },
+        {
+          "name": "header-content-type",
+          "type": "string",
+          "description": "<code>Content-Type</code> request header. Dropped entirely when the request has no body.",
+          "fieldName": "headerContentType",
+          "surface": "option",
+          "default": "\"application/json\"",
+          "inheritedFrom": "@excom/fetchable-element"
+        },
+        {
+          "name": "start-method",
+          "type": "string",
+          "description": "Which WebAuthn ceremony to run.",
+          "fieldName": "startMethod",
+          "surface": "option",
+          "values": "\"register\" | \"authenticate\""
+        },
+        {
+          "name": "verify-url",
+          "type": "string",
+          "description": "Endpoint that verifies the credential produced by the browser prompt (your server&#39;s <code>verifyRegistrationResponse</code> / <code>verifyAuthenticationResponse</code>). Receives the credential as the request body.",
+          "fieldName": "verifyUrl",
+          "surface": "option",
+          "values": "<URL>"
+        },
+        {
+          "name": "is-error",
+          "type": "boolean",
+          "description": "The most recent request failed (non-2xx status, network error, or a thrown error other than <code>AbortError</code>). Fires with the <code>error</code> event.",
+          "fieldName": "isError",
+          "surface": "state",
+          "inheritedFrom": "@excom/fetchable-element"
+        },
+        {
+          "name": "is-loading",
+          "type": "boolean",
+          "description": "A request is currently in flight.",
+          "fieldName": "isLoading",
+          "surface": "state",
+          "inheritedFrom": "@excom/fetchable-element"
+        },
+        {
+          "name": "is-success",
+          "type": "boolean",
+          "description": "The most recent request resolved successfully. Mutually exclusive with <code>is-error</code>.",
+          "fieldName": "isSuccess",
+          "surface": "state",
+          "inheritedFrom": "@excom/fetchable-element"
+        }
+      ],
+      "events": [
+        {
+          "name": "web-authn-error",
+          "description": "Dispatched when the request fails — non-2xx status, network error, or a thrown error. <code>event.detail</code> is the error payload (see <code>provision</code>). Not dispatched for aborted requests.",
+          "type": "FetchableErrorEvent",
+          "typeExpanded": "CustomEvent & { type: \"{tag}-error\"; detail: { bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; } | { message: string; stack?: string }; bubbles: true; cancelable: true; composed: true }",
+          "inheritedFrom": "@excom/fetchable-element"
+        },
+        {
+          "name": "web-authn-loading",
+          "description": "Dispatched immediately before the request is sent.",
+          "type": "FetchableLoadingEvent",
+          "typeExpanded": "CustomEvent & { type: \"{tag}-loading\"; detail: void; bubbles: true; cancelable: true; composed: true }",
+          "inheritedFrom": "@excom/fetchable-element"
+        },
+        {
+          "name": "web-authn-submit",
+          "description": "Internal — dispatched once the browser ceremony (register or authenticate) resolves, just before the verify-url fetch runs. The credential is the request body. Default action calls <code>doFetch()</code>.",
+          "type": "WebAuthnSubmitEvent",
+          "typeExpanded": "CustomEvent & { type: \"web-authn-submit\"; detail: [url: string, requestInit: RequestInit]; bubbles: true; cancelable: true; composed: true }",
+          "defaultAction": "Calls <code>doFetch(url, requestInit)</code> with the event&#39;s detail (the verify-url request)."
+        },
+        {
+          "name": "web-authn-success",
+          "description": "Dispatched when the request resolves successfully. <code>event.detail</code> is the parsed response (see <code>provision</code>).",
+          "type": "FetchableSuccessEvent",
+          "typeExpanded": "CustomEvent & { type: \"{tag}-success\"; detail: { bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; }; bubbles: true; cancelable: true; composed: true }",
+          "inheritedFrom": "@excom/fetchable-element"
+        }
+      ],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [],
+      "listens": [
+        {
+          "name": "submit",
+          "description": "The default action of the <code>&lt;form&gt;</code> matched by <code>form-ref</code>; prevented, then starts the ceremony.",
+          "type": "WebAuthnNativeSubmitEvent",
+          "typeExpanded": "SubmitEvent & { type: \"submit\"; bubbles: true; cancelable: true; composed: false; }"
+        }
+      ],
+      "commands": [
+        {
+          "name": "--submit",
+          "description": "Starts the ceremony programmatically (<code>&lt;button command=&quot;--submit&quot; commandfor=&quot;…&quot;&gt;</code>) — the only option when <code>form-ref</code> points to a form that isn&#39;t a descendant."
+        }
+      ],
+      "defaultActions": [
+        {
+          "name": "web-authn-submit",
+          "description": "Calls <code>doFetch(url, requestInit)</code> with the event&#39;s detail (the verify-url request)."
+        }
+      ],
+      "expectedChildren": [],
+      "provisions": [
+        {
+          "name": "provision",
+          "type": "FetchResponse",
+          "typeExpanded": "{ bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; }",
+          "description": "Response payload on success, or error payload on failure. Success shape: <code>{ status, statusText, ok, headers, url, redirected, bodyUsed, type, body }</code>. Failure shape is either that same response shape (server responded with an error status) or <code>{ message, stack }</code> (request never completed). Not reflected as an attribute.",
+          "fieldName": "provision",
+          "inheritedFrom": "@excom/fetchable-element"
+        }
+      ]
+    }
+  ],
+  "exportedFiles": {}
+}

package/support/tests/authenticate.view.test.ts

@@ -0,0 +1,28 @@
+import "@excom/quark-sheet";
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+  spyFetch,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { mountView, readDemo } from "@excom/quark/support/tests/view-helpers";
+
+describe("authenticate view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("mounts the authenticate form", async () => {
+    spyFetch({
+      status: 200,
+      body: JSON.stringify({ challenge: "x" }),
+    });
+    const { root } = await mountView(readDemo(import.meta.url, "authenticate"));
+    expect(root.querySelector("web-authn")?.getAttribute("start-method")).toBe(
+      "authenticate",
+    );
+    expect(root.querySelector("button")?.textContent).toMatch(/passkey/);
+  });
+});

package/support/tests/register.view.test.ts

@@ -0,0 +1,29 @@
+import "@excom/quark-sheet";
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+  spyFetch,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { flush, mountView, readDemo } from "@excom/quark/support/tests/view-helpers";
+
+describe("register view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("mounts the register form (no authenticator in happy-dom)", async () => {
+    spyFetch({
+      status: 200,
+      body: JSON.stringify({ rp: { name: "demo" }, user: { id: "1" }, challenge: "x" }),
+    });
+    const { root } = await mountView(readDemo(import.meta.url, "register"));
+    expect(root.querySelector("web-authn")?.getAttribute("start-method")).toBe(
+      "register",
+    );
+    expect(root.querySelector('input[name="username"]')).toBeTruthy();
+    await flush();
+  });
+});