@terminal3/seal-web 0.3.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. |
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/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.3.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",