@terminal3/seal-web 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -61,7 +61,7 @@ Each endpoint is a URL or path. The four that act on one item or request carry `
61
61
  | Entry | Method | Takes | Answers |
62
62
  | --- | --- | --- | --- |
63
63
  | `fetch` | | `(url, init)` | A `Response`. Optional; `fetch` by default. |
64
- | `passkey` | GET | | `{ credential_id }` of the customer's registered passkey, read before each passkey prompt; `credential_id` is `null` when there is none |
64
+ | `passkey` | GET | | `{ credentials: [{ credential_id, transports }] }`, every passkey the customer has registered with the transports it reported, read before each passkey prompt; empty when there is none |
65
65
  | `passkey` | POST | `{ nonce, registration }`, below | |
66
66
  | `nonce` | POST | `{ purpose: "register" }` | `{ nonce }`, single-use, for the customer's signed-in session |
67
67
  | `nonce` | POST | `{ purpose: "bind" }` or `{ purpose: "get" }` | `{ nonce, sid }`, single-use for that purpose |
@@ -78,9 +78,9 @@ Your app server verifies what the browser sends and relays each call to T3N; the
78
78
  ## Keys and passkeys
79
79
 
80
80
  - **Session key.** `startSession` makes a P-256 ECDH key pair with WebCrypto as non-extractable, so the private key never exists outside the browser's key store. It lives in IndexedDB for the session (10 minutes idle, 30 minutes at most).
81
- - **Registration.** `registerPasskey` runs a WebAuthn registration ceremony over a `register` nonce, with user verification required. Its challenge is SHA-256 of the JCS of `{ t: "t3n-seal/register", nonce }`. It excludes the customer's registered credential, so a device that holds it makes no second one. It posts `{ nonce, registration }`, where `registration` is `{ credential_id, clientDataJSON, attestationObject, authenticatorData?, publicKey?, publicKeyAlgorithm?, transports }`: the binary members base64url, `publicKey` the SPKI and `publicKeyAlgorithm` its COSE algorithm where the browser reports them. Your IdP consumes the nonce, then checks that `clientDataJSON` has `type` `webauthn.create`, that challenge and your origin, and that the authenticator data has your RP ID hash and the user-present and user-verified flags. It stores the credential ID and public key from the attestation's authenticator data; `publicKey` must match them. Attestation is `none`, so the ceremony proves freshness and the origin, not the authenticator: accept a registration only within a fresh sign-in.
81
+ - **Registration.** `registerPasskey` runs a WebAuthn registration ceremony over a `register` nonce, with a discoverable credential and user verification required. Its challenge is SHA-256 of the JCS of `{ t: "t3n-seal/register", nonce }`. It excludes every passkey the customer has registered, so a device that holds one makes no other. A new passkey is added to the customer's, not swapped for one. It posts `{ nonce, registration }`, where `registration` is `{ credential_id, clientDataJSON, attestationObject, authenticatorData?, publicKey?, publicKeyAlgorithm?, transports }`: the binary members base64url, `publicKey` the SPKI and `publicKeyAlgorithm` its COSE algorithm where the browser reports them. Your IdP consumes the nonce, then checks that `clientDataJSON` has `type` `webauthn.create`, that challenge and your origin, and that the authenticator data has your RP ID hash and the user-present and user-verified flags. It stores the credential ID and public key from the attestation's authenticator data, beside `transports`, and keeps the customer's earlier passkeys; `publicKey` must match them. Attestation is `none`, so the ceremony proves freshness and the origin, not the authenticator: accept a registration only within a fresh sign-in.
82
82
  - **Signing key.** `startSession({ sid, nonce, signing: true })` also makes a P-256 ECDSA key pair, non-extractable, kept in the same record for the same life, for fields the customer signs (WebCrypto cannot use one key for both).
83
- - **Binding.** The customer's passkey binds the session key's public half to their consent: an assertion over SHA-256 of the JCS (RFC 8785) of `{ t: "t3n-seal/bind", kid, sid, nonce }`. Your IdP verifies it against the registered passkey and only then puts `seal_jwk` in the assistant's delegation token. With a signing key, the one assertion covers both, over `{ t: "t3n-seal/bind", kid, sig_kid, sid, nonce }`. Your IdP builds that statement itself, deriving `kid` and `sig_kid` as the RFC 7638 thumbprints of the posted `seal_jwk` and `seal_sig_jwk`, and refuses an assertion over the statement without `sig_kid` whenever `seal_sig_jwk` is posted: that assertion does not cover the signing key. Only then does it put `seal_sig_jwk` beside `seal_jwk`, copy both into every token it exchanges, and list both in its row's `subject_claims`.
83
+ - **Binding.** The customer's passkey binds the session key's public half to their consent: an assertion over SHA-256 of the JCS (RFC 8785) of `{ t: "t3n-seal/bind", kid, sid, nonce }`. Your IdP verifies it against whichever of the customer's registered passkeys `credential_id` names and only then puts `seal_jwk` in the assistant's delegation token. With a signing key, the one assertion covers both, over `{ t: "t3n-seal/bind", kid, sig_kid, sid, nonce }`. Your IdP builds that statement itself, deriving `kid` and `sig_kid` as the RFC 7638 thumbprints of the posted `seal_jwk` and `seal_sig_jwk`, and refuses an assertion over the statement without `sig_kid` whenever `seal_sig_jwk` is posted: that assertion does not cover the signing key. Only then does it put `seal_sig_jwk` beside `seal_jwk`, copy both into every token it exchanges, and list both in its row's `subject_claims`.
84
84
  - **Fresh unlock.** An item that asks for one (a card number) opens only after another assertion, over `{ t: "t3n-seal/get", ref, sid, nonce }`.
85
85
 
86
86
  ## Formats
@@ -93,7 +93,7 @@ Your app server verifies what the browser sends and relays each call to T3N; the
93
93
 
94
94
  | Function | |
95
95
  | --- | --- |
96
- | `registerPasskey({ id, name })` | Registers the customer's passkey on this device, unless it already holds their registered credential; answers the credential ID. |
96
+ | `registerPasskey({ id, name })` | Registers a passkey for the customer on this device, unless it already holds one of theirs; answers the new credential ID, or `null` when it already held one. |
97
97
  | `startSession({ sid, nonce, signing? })` | Makes and binds a session key, and a signing key with `signing`; answers the session key's public JWK. |
98
98
  | `ensureSession({ signing? })` | Binds a session key with a fresh nonce if none is live, or, with `signing`, has no signing key. |
99
99
  | `hasSession(sid?)`, `reset()` | Whether a live session key is bound; delete it. |
@@ -138,7 +138,7 @@ A field sealed to the customer reaches the recipient agent as `customer_jwe` in
138
138
 
139
139
  ## Elements
140
140
 
141
- - `<t3-safebox ref="sealed:…" label="…">` shows a sealed item once the customer opens it, for a minute. `auto-open` opens it on connection; `source="name"` fetches it from `api.sources.name`. An item with a `confirm` button fires `seal-confirmed` after the `confirm` endpoint answers, or `seal-confirm` (with `run_id`) for a confirmation your app runs itself.
141
+ - `<t3-safebox ref="sealed:…" label="…">` shows a sealed item once the customer opens it, for a minute. `auto-open` opens it on connection; `source="name"` fetches it from `api.sources.name`. An item with a `confirm` button fires `seal-confirmed` after the `confirm` endpoint answers, or `seal-confirm` (with `run_id`) for a confirmation your app runs itself. `decline-label="…"` adds a second button beside an item's own confirmation (not a `run_id` one): it fires `seal-declined` with the reference and records nothing, so your app decides what a decline means.
142
142
  - `<t3-safebox-form ref="request:…">` draws a sealed request from its verified description, and fires `seal-submitted` once the answers are sent.
143
143
  - Both may be in the page before `configure` runs: they wait in `data-state="waiting"` and start once it has. Both render again on each later `configure`; their shadow root keeps the mode it was attached with.
144
144
  - Both reflect their state in `data-state`, and take their accent colour from the CSS custom properties `--seal-accent` and `--seal-accent-soft`.
package/dist/config.d.ts CHANGED
@@ -8,7 +8,7 @@ export interface SealApi {
8
8
  /** Sends a request with the customer's app session. Defaults to `fetch`; keep `init.headers`. */
9
9
  fetch?: (url: string, init: RequestInit) => Promise<Response>;
10
10
  /**
11
- * GET answers `{ credential_id }`, `null` when she has none; POST takes
11
+ * GET answers `{ credentials: [{ credential_id, transports }] }`, empty when she has none; POST takes
12
12
  * `{ nonce, registration }`, the WebAuthn registration response made over a
13
13
  * `register` nonce.
14
14
  */
package/dist/elements.js CHANGED
@@ -1,6 +1,8 @@
1
- // <t3-safebox ref="sealed:…" label="…" source="…" auto-open>: a sealed item,
2
- // opened only in this browser and dropped from the page a minute later, or
3
- // as soon as the element leaves the page.
1
+ // <t3-safebox ref="sealed:…" label="…" source="…" decline-label="…" auto-open>:
2
+ // a sealed item, opened only in this browser and dropped from the page a
3
+ // minute later, or as soon as the element leaves the page. An item with a
4
+ // confirmation of its own (any `confirm.kind` but "run") also offers
5
+ // `decline-label`'s button, when the page sets one.
4
6
  // <t3-safebox-form ref="request:…">: a sealed request, drawn from its signed
5
7
  // description. Both wait in `data-state="waiting"` until `configure` has run,
6
8
  // then render into a shadow root of the configured mode, attached once, and
@@ -38,7 +40,8 @@ const STYLE = `
38
40
  .f span{color:#7a7a82;font-size:12.5px}
39
41
  .f b{font-weight:600;text-align:right}
40
42
  .mono{font-family:ui-monospace,"SF Mono",Menlo,monospace;letter-spacing:.02em}
41
- .row{display:flex;align-items:center;justify-content:space-between;gap:10px;margin-top:12px}
43
+ .row{display:flex;align-items:center;justify-content:space-between;gap:10px;margin-top:12px;flex-wrap:wrap}
44
+ .acts{display:flex;gap:8px;margin-left:auto}
42
45
  button{font:inherit;font-weight:600;border-radius:10px;padding:8px 14px;cursor:pointer;border:0;background:var(--seal-accent,#c8102e);color:#fff}
43
46
  button.ghost{background:#fff;color:#1d1d1f;border:1px solid #d9d3cd}
44
47
  button:disabled{opacity:.55;cursor:default}
@@ -66,7 +69,7 @@ const rpName = () => configured()?.rpName ?? "";
66
69
  const shadowMode = () => configured()?.shadow ?? "closed";
67
70
  /** Defines both elements once; a no-op where they are already defined. */
68
71
  export function defineElements() {
69
- var _T3Safebox_root, _T3Safebox_unlisten, _T3Safebox_data, _T3Safebox_label, _T3Safebox_confirmed, _T3Safebox_error, _T3Safebox_hideTimer, _T3SafeboxForm_root, _T3SafeboxForm_unlisten, _T3SafeboxForm_desc, _T3SafeboxForm_files, _T3SafeboxForm_error;
72
+ var _T3Safebox_root, _T3Safebox_unlisten, _T3Safebox_data, _T3Safebox_label, _T3Safebox_confirmed, _T3Safebox_declined, _T3Safebox_confirming, _T3Safebox_error, _T3Safebox_hideTimer, _T3SafeboxForm_root, _T3SafeboxForm_unlisten, _T3SafeboxForm_desc, _T3SafeboxForm_files, _T3SafeboxForm_error;
70
73
  class T3Safebox extends HTMLElement {
71
74
  constructor() {
72
75
  super(...arguments);
@@ -75,6 +78,8 @@ export function defineElements() {
75
78
  _T3Safebox_data.set(this, null);
76
79
  _T3Safebox_label.set(this, null);
77
80
  _T3Safebox_confirmed.set(this, false);
81
+ _T3Safebox_declined.set(this, false);
82
+ _T3Safebox_confirming.set(this, false);
78
83
  _T3Safebox_error.set(this, null);
79
84
  _T3Safebox_hideTimer.set(this, void 0);
80
85
  }
@@ -122,9 +127,12 @@ export function defineElements() {
122
127
  }
123
128
  }
124
129
  async confirm() {
125
- const btn = __classPrivateFieldGet(this, _T3Safebox_root, "f")?.querySelector("#confirm");
126
- if (btn)
127
- btn.disabled = true;
130
+ __classPrivateFieldSet(this, _T3Safebox_confirming, true, "f");
131
+ for (const id of ["#confirm", "#decline"]) {
132
+ const btn = __classPrivateFieldGet(this, _T3Safebox_root, "f")?.querySelector(id);
133
+ if (btn)
134
+ btn.disabled = true;
135
+ }
128
136
  const c = __classPrivateFieldGet(this, _T3Safebox_data, "f")?.confirm ?? {};
129
137
  const ref = this.getAttribute("ref");
130
138
  try {
@@ -144,6 +152,18 @@ export function defineElements() {
144
152
  __classPrivateFieldSet(this, _T3Safebox_error, messageOf(e), "f");
145
153
  this.render();
146
154
  }
155
+ finally {
156
+ __classPrivateFieldSet(this, _T3Safebox_confirming, false, "f");
157
+ }
158
+ }
159
+ /** The customer's "not this one", for the app to act on: nothing is recorded in T3N. */
160
+ decline() {
161
+ if (__classPrivateFieldGet(this, _T3Safebox_confirming, "f") || __classPrivateFieldGet(this, _T3Safebox_confirmed, "f"))
162
+ return;
163
+ __classPrivateFieldSet(this, _T3Safebox_declined, true, "f");
164
+ this.setAttribute("data-declined", "true");
165
+ this.dispatchEvent(new CustomEvent("seal-declined", { bubbles: true, composed: true, detail: { ref: this.getAttribute("ref") } }));
166
+ this.render();
147
167
  }
148
168
  hide() {
149
169
  __classPrivateFieldSet(this, _T3Safebox_data, null, "f");
@@ -174,12 +194,14 @@ export function defineElements() {
174
194
  else if (d) {
175
195
  const fields = Array.isArray(d.fields) ? d.fields : [];
176
196
  const c = d.confirm;
197
+ const answered = __classPrivateFieldGet(this, _T3Safebox_confirmed, "f") || __classPrivateFieldGet(this, _T3Safebox_declined, "f");
198
+ const declineLabel = c?.kind !== "run" ? this.getAttribute("decline-label") : null;
177
199
  body = `${d.summary ? `<div class="sum">${esc(d.summary)}</div>` : ""}<div class="fields">${fields
178
200
  .map((f) => `<div class="f" data-field="${esc(f.label)}"><span>${esc(f.label)}</span><b class="${f.mono ? "mono" : ""}">${esc(f.value)}</b></div>`)
179
201
  .join("")}</div>
180
- ${__classPrivateFieldGet(this, _T3Safebox_confirmed, "f") ? `<div class="ok">Confirmed</div>` : ""}
202
+ ${__classPrivateFieldGet(this, _T3Safebox_confirmed, "f") ? `<div class="ok">Confirmed</div>` : __classPrivateFieldGet(this, _T3Safebox_declined, "f") ? `<div class="note">You said this is not the one.</div>` : ""}
181
203
  <div class="row"><span class="note">Decrypted in this browser only.</span>
182
- ${c && !__classPrivateFieldGet(this, _T3Safebox_confirmed, "f") ? `<button id="confirm">${esc(c.label ?? "Confirm")}</button>` : `<button class="ghost" id="hide">Hide</button>`}</div>`;
204
+ ${c && !answered ? `<span class="acts">${declineLabel ? `<button class="ghost" id="decline">${esc(declineLabel)}</button>` : ""}<button id="confirm">${esc(c.label ?? "Confirm")}</button></span>` : `<button class="ghost" id="hide">Hide</button>`}</div>`;
183
205
  }
184
206
  else if (state === "error") {
185
207
  body = `<div class="err">${esc(__classPrivateFieldGet(this, _T3Safebox_error, "f"))}</div><div class="row"><span class="note">Only this browser can open it.</span><button id="reveal">Open</button></div>`;
@@ -196,9 +218,10 @@ export function defineElements() {
196
218
  root.querySelector("#reveal")?.addEventListener("click", () => void this.reveal());
197
219
  root.querySelector("#hide")?.addEventListener("click", () => this.hide());
198
220
  root.querySelector("#confirm")?.addEventListener("click", () => void this.confirm());
221
+ root.querySelector("#decline")?.addEventListener("click", () => this.decline());
199
222
  }
200
223
  }
201
- _T3Safebox_root = new WeakMap(), _T3Safebox_unlisten = new WeakMap(), _T3Safebox_data = new WeakMap(), _T3Safebox_label = new WeakMap(), _T3Safebox_confirmed = new WeakMap(), _T3Safebox_error = new WeakMap(), _T3Safebox_hideTimer = new WeakMap();
224
+ _T3Safebox_root = new WeakMap(), _T3Safebox_unlisten = new WeakMap(), _T3Safebox_data = new WeakMap(), _T3Safebox_label = new WeakMap(), _T3Safebox_confirmed = new WeakMap(), _T3Safebox_declined = new WeakMap(), _T3Safebox_confirming = new WeakMap(), _T3Safebox_error = new WeakMap(), _T3Safebox_hideTimer = new WeakMap();
202
225
  class T3SafeboxForm extends HTMLElement {
203
226
  constructor() {
204
227
  super(...arguments);
package/dist/passkey.d.ts CHANGED
@@ -17,22 +17,23 @@ export interface Registration {
17
17
  transports: string[];
18
18
  }
19
19
  /**
20
- * Registers the user's passkey on this device and answers its credential ID.
21
- * A device that already holds the registered credential makes no other
22
- * (`excludeCredentials`), and that ID is answered. The ceremony's challenge
23
- * is SHA-256(JCS {t: "t3n-seal/register", nonce}) over a single-use
24
- * `register` nonce from the IdP, which verifies the ceremony and takes the
25
- * public key from its attestation.
20
+ * Registers a discoverable passkey for the user on this device, beside any
21
+ * they already have, and answers its credential ID. A device that already
22
+ * holds one of their passkeys makes no other (`excludeCredentials`) and
23
+ * answers `null`. The ceremony's challenge is SHA-256(JCS {t:
24
+ * "t3n-seal/register", nonce}) over a single-use `register` nonce from the
25
+ * IdP, which verifies the ceremony and takes the public key from its
26
+ * attestation.
26
27
  */
27
28
  export declare function registerPasskey(user: {
28
29
  id: string;
29
30
  name: string;
30
- }): Promise<string>;
31
+ }): Promise<string | null>;
31
32
  export interface Assertion {
32
33
  credential_id: string;
33
34
  authenticatorData: string;
34
35
  clientDataJSON: string;
35
36
  signature: string;
36
37
  }
37
- /** A passkey assertion over SHA-256(JCS(statement)) with the user's registered credential, for the IdP to verify. */
38
+ /** A passkey assertion over SHA-256(JCS(statement)) with any of the user's registered passkeys, for the IdP to verify. */
38
39
  export declare function assertStatement(statement: Record<string, string>): Promise<Assertion>;
package/dist/passkey.js CHANGED
@@ -23,15 +23,29 @@ function rpId() {
23
23
  function challengeFor(statement) {
24
24
  return sha256(utf8(canonicalJson(statement)));
25
25
  }
26
- /** The user's registered credential from the `passkey` endpoint, or `null` when there is none. */
26
+ /**
27
+ * The user's registered passkeys from the `passkey` endpoint, each with the
28
+ * transports its authenticator reported, so the browser can route the prompt
29
+ * to where the passkey lives rather than guess.
30
+ */
27
31
  async function registered() {
28
- const { credential_id: id } = await call("passkey", { method: "GET" });
29
- if (id === null || id === undefined)
30
- return null;
31
- const raw = typeof id === "string" ? fromB64u(id) : null;
32
- if (typeof id !== "string" || !raw)
33
- throw new SealError("bad_response", "The app's credential_id is not base64url.");
34
- return { id, raw };
32
+ const { credentials } = await call("passkey", { method: "GET" });
33
+ if (!Array.isArray(credentials))
34
+ throw new SealError("bad_response", "The app's answer has no credentials list.");
35
+ return credentials.map((c) => {
36
+ const { credential_id: id, transports } = (typeof c === "object" && c !== null ? c : {});
37
+ const raw = typeof id === "string" ? fromB64u(id) : null;
38
+ if (typeof id !== "string" || !raw)
39
+ throw new SealError("bad_response", "The app's credential_id is not base64url.");
40
+ if (!Array.isArray(transports) || transports.some((t) => typeof t !== "string")) {
41
+ throw new SealError("bad_response", "The app's transports are not a list of strings.");
42
+ }
43
+ const descriptor = { type: "public-key", id: raw };
44
+ // Unchecked against the enum: WebAuthn ignores transports it does not know.
45
+ if (transports.length > 0)
46
+ descriptor.transports = transports;
47
+ return { id, descriptor };
48
+ });
35
49
  }
36
50
  /**
37
51
  * Runs one WebAuthn call. A rejection becomes a `SealError`: `passkey_cancelled`
@@ -64,12 +78,13 @@ async function ceremony(run) {
64
78
  }
65
79
  }
66
80
  /**
67
- * Registers the user's passkey on this device and answers its credential ID.
68
- * A device that already holds the registered credential makes no other
69
- * (`excludeCredentials`), and that ID is answered. The ceremony's challenge
70
- * is SHA-256(JCS {t: "t3n-seal/register", nonce}) over a single-use
71
- * `register` nonce from the IdP, which verifies the ceremony and takes the
72
- * public key from its attestation.
81
+ * Registers a discoverable passkey for the user on this device, beside any
82
+ * they already have, and answers its credential ID. A device that already
83
+ * holds one of their passkeys makes no other (`excludeCredentials`) and
84
+ * answers `null`. The ceremony's challenge is SHA-256(JCS {t:
85
+ * "t3n-seal/register", nonce}) over a single-use `register` nonce from the
86
+ * IdP, which verifies the ceremony and takes the public key from its
87
+ * attestation.
73
88
  */
74
89
  export async function registerPasskey(user) {
75
90
  const cfg = current();
@@ -84,15 +99,16 @@ export async function registerPasskey(user) {
84
99
  user: { id: utf8(user.id), name: user.name, displayName: user.name },
85
100
  challenge,
86
101
  pubKeyCredParams: [{ type: "public-key", alg: -7 }],
87
- excludeCredentials: known ? [{ type: "public-key", id: known.raw }] : [],
88
- authenticatorSelection: { residentKey: "preferred", userVerification: "required" },
102
+ excludeCredentials: known.map((k) => k.descriptor),
103
+ // A required discoverable credential is what password managers take; "preferred" lets the browser settle on the platform authenticator.
104
+ authenticatorSelection: { residentKey: "required", requireResidentKey: true, userVerification: "required" },
89
105
  attestation: "none",
90
106
  },
91
107
  })));
92
108
  }
93
109
  catch (e) {
94
- if (known && e instanceof SealError && e.code === "passkey_exists")
95
- return known.id;
110
+ if (known.length > 0 && e instanceof SealError && e.code === "passkey_exists")
111
+ return null;
96
112
  throw e;
97
113
  }
98
114
  if (!cred)
@@ -118,7 +134,7 @@ export async function registerPasskey(user) {
118
134
  await call("passkey", { method: "POST", body: { nonce, registration } });
119
135
  return id;
120
136
  }
121
- /** A passkey assertion over SHA-256(JCS(statement)) with the user's registered credential, for the IdP to verify. */
137
+ /** A passkey assertion over SHA-256(JCS(statement)) with any of the user's registered passkeys, for the IdP to verify. */
122
138
  export async function assertStatement(statement) {
123
139
  const known = await registered();
124
140
  const challenge = await challengeFor(statement);
@@ -127,7 +143,7 @@ export async function assertStatement(statement) {
127
143
  challenge,
128
144
  rpId: rpId(),
129
145
  userVerification: "required",
130
- ...(known ? { allowCredentials: [{ type: "public-key", id: known.raw }] } : {}),
146
+ ...(known.length > 0 ? { allowCredentials: known.map((k) => k.descriptor) } : {}),
131
147
  },
132
148
  })));
133
149
  if (!cred)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@terminal3/seal-web",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "type": "module",
5
5
  "description": "T3n sealed delivery in the browser - open items sealed to a device-bound key, and fill signed forms whose answers only their named recipients can read, with no runtime dependencies",
6
6
  "main": "dist/index.js",