provared 0.1.0

package/src/jws.js

@@ -0,0 +1,235 @@
+// The signed envelope: JSON Web Signature (RFC 7515) in the general JSON
+// serialisation (section 7.2.1), as the format description, sections 3.1 to
+// 3.5, narrows it.
+//
+// Each layout is built in one place, here, and used by both the writers and
+// the checker.
+
+import { Refusal, canonicalJson, fingerprint, fromBase64url, fromUtf8, parseCanonical, toBase64url, utf8 } from './encoding.js';
+
+/** The largest record, in bytes. */
+export const MAX_RECORD_BYTES = 65536;
+
+/**
+ * The kinds of record. For each: the "type" of its content, and the exact
+ * protected header of each signature, in order. A checker compares protected
+ * headers byte for byte with these texts and interprets nothing else.
+ */
+export const KINDS = {
+  slip: {
+    type: 'provared.slip.v0',
+    passkey: true,
+    protected: ['{"typ":"vnd.provared.slip.v0+json","alg":"prova.red/webauthn/v0"}'],
+  },
+  stub: {
+    type: 'provared.stub.v0',
+    protected: ['{"typ":"vnd.provared.stub.v0+json","alg":"Ed25519"}', '{"typ":"vnd.provared.stub.v0+json","alg":"ML-DSA-87"}'],
+  },
+  countersignature: {
+    type: 'provared.countersignature.v0',
+    protected: [
+      '{"typ":"vnd.provared.countersignature.v0+json","alg":"Ed25519"}',
+      '{"typ":"vnd.provared.countersignature.v0+json","alg":"ML-DSA-87"}',
+    ],
+  },
+  approval: {
+    type: 'provared.approval.v0',
+    passkey: true,
+    protected: ['{"typ":"vnd.provared.approval.v0+json","alg":"prova.red/webauthn/v0"}'],
+  },
+  refusal: {
+    type: 'provared.refusal.v0',
+    protected: ['{"typ":"vnd.provared.refusal.v0+json","alg":"Ed25519"}', '{"typ":"vnd.provared.refusal.v0+json","alg":"ML-DSA-87"}'],
+  },
+  terms: {
+    type: 'provared.terms.v0',
+    protected: ['{"typ":"vnd.provared.terms.v0+json","alg":"Ed25519"}', '{"typ":"vnd.provared.terms.v0+json","alg":"ML-DSA-87"}'],
+  },
+  cancellation: {
+    type: 'provared.cancellation.v0',
+    passkey: true,
+    protected: ['{"typ":"vnd.provared.cancellation.v0+json","alg":"prova.red/webauthn/v0"}'],
+  },
+  acknowledgement: {
+    type: 'provared.acknowledgement.v0',
+    protected: ['{"typ":"vnd.provared.acknowledgement.v0+json","alg":"Ed25519"}', '{"typ":"vnd.provared.acknowledgement.v0+json","alg":"ML-DSA-87"}'],
+  },
+  vouching: {
+    type: 'provared.vouching.v0',
+    protected: ['{"typ":"vnd.provared.vouching.v0+json","alg":"Ed25519"}', '{"typ":"vnd.provared.vouching.v0+json","alg":"ML-DSA-87"}'],
+  },
+  withdrawal: {
+    type: 'provared.withdrawal.v0',
+    protected: ['{"typ":"vnd.provared.withdrawal.v0+json","alg":"Ed25519"}', '{"typ":"vnd.provared.withdrawal.v0+json","alg":"ML-DSA-87"}'],
+  },
+  pass: {
+    type: 'provared.pass.v0',
+    protected: ['{"typ":"vnd.provared.pass.v0+json","alg":"Ed25519"}', '{"typ":"vnd.provared.pass.v0+json","alg":"ML-DSA-87"}'],
+  },
+  seal: {
+    type: 'provared.seal.v0',
+    protected: [
+      '{"typ":"vnd.provared.seal.v0+json","alg":"Ed25519"}',
+      '{"typ":"vnd.provared.seal.v0+json","alg":"ML-DSA-87"}',
+      '{"typ":"vnd.provared.seal.v0+json","alg":"SLH-DSA-SHA2-256s"}',
+    ],
+  },
+};
+
+const ALL_PROTECTED = new Map();
+for (const [kind, k] of Object.entries(KINDS)) {
+  for (const text of k.protected) ALL_PROTECTED.set(text, kind);
+}
+
+/**
+ * The protected headers of a kind, in base64url, in signature order.
+ * @param {'slip'|'stub'|'countersignature'} kind
+ * @returns {string[]}
+ */
+export function protectedHeaders(kind) {
+  return KINDS[kind].protected.map((text) => toBase64url(utf8(text)));
+}
+
+/**
+ * The bytes a signature covers (RFC 7515 section 5.1): the protected header
+ * in base64url, a full stop, the content in base64url.
+ * @param {string} protectedB64
+ * @param {string} payloadB64
+ * @returns {Uint8Array}
+ */
+export function signingInput(protectedB64, payloadB64) {
+  return utf8(protectedB64 + '.' + payloadB64);
+}
+
+/**
+ * The size of a record, as the format description, section 3.1, measures it:
+ * the lengths of its "payload" and of every text value in its signature
+ * entries, added up. It does not depend on how the JSON around them is
+ * written.
+ * @param {any} record
+ * @returns {number}
+ */
+export function recordSize(record) {
+  let size = typeof record.payload === 'string' ? record.payload.length : 0;
+  if (!Array.isArray(record.signatures)) return size;
+  for (const s of record.signatures) {
+    if (s === null || typeof s !== 'object') continue;
+    for (const v of Object.values(s)) size += typeof v === 'string' ? v.length : 0;
+    if (s.header !== null && typeof s.header === 'object') {
+      for (const v of Object.values(s.header)) size += typeof v === 'string' ? v.length : 0;
+    }
+  }
+  return size;
+}
+
+/**
+ * A writer's check that what it has made is small enough to be accepted.
+ * @param {any} record
+ * @returns {any} the record
+ */
+export function withinSize(record) {
+  if (recordSize(record) > MAX_RECORD_BYTES) throw new Refusal('too-large', 'The record would be larger than 65,536 bytes.');
+  return record;
+}
+
+function exactMembers(object, names, what) {
+  if (object === null || typeof object !== 'object' || Array.isArray(object)) {
+    throw new Refusal('bad-envelope', `${what} must be an object.`);
+  }
+  const have = Object.keys(object).sort();
+  const want = [...names].sort();
+  if (have.length !== want.length || have.some((n, i) => n !== want[i])) {
+    throw new Refusal('bad-envelope', `${what} must hold exactly: ${want.join(', ')}.`);
+  }
+}
+
+/**
+ * @typedef {object} ParsedRecord
+ * @property {string} kind
+ * @property {string} payloadB64 the content exactly as carried
+ * @property {Uint8Array} contentBytes the content bytes, exactly as signed
+ * @property {any} content the content, read from those bytes
+ * @property {string} fingerprint the fingerprint of the record
+ * @property {{protectedB64: string, signature: Uint8Array, header?: any}[]} signatures
+ */
+
+/**
+ * Read a record and confirm its envelope, its labels and the canonical form
+ * of its content. This checks no signature and no field of the content
+ * other than "type".
+ *
+ * @param {any} record the record as a JavaScript object
+ * @param {string} kind the kind of record expected in this place: one of the names of KINDS
+ * @returns {Promise<ParsedRecord>}
+ */
+export async function parseRecord(record, kind) {
+  const expected = KINDS[kind];
+  exactMembers(record, ['payload', 'signatures'], 'A record');
+  if (typeof record.payload !== 'string') throw new Refusal('bad-envelope', '"payload" must be text.');
+  if (!Array.isArray(record.signatures)) throw new Refusal('bad-envelope', '"signatures" must be a list.');
+
+  // The size is measured before anything is decoded.
+  if (recordSize(record) > MAX_RECORD_BYTES) throw new Refusal('too-large', 'The record is larger than 65,536 bytes.');
+
+  // Labels first: what kind of record does each signature say this is?
+  const signatures = [];
+  const seen = [];
+  for (const s of record.signatures) {
+    exactMembers(s, expected.passkey ? ['header', 'protected', 'signature'] : ['protected', 'signature'], 'A signature entry');
+    if (typeof s.protected !== 'string' || typeof s.signature !== 'string') {
+      throw new Refusal('bad-envelope', '"protected" and "signature" must be text.');
+    }
+    const text = fromUtf8(fromBase64url(s.protected), 'unknown-type');
+    if (!ALL_PROTECTED.has(text)) {
+      throw new Refusal('unknown-type', 'A signature carries a label that is not one of the known labels.');
+    }
+    if (ALL_PROTECTED.get(text) !== kind) {
+      throw new Refusal('payload-type-mismatch', `A signature is labelled as a ${ALL_PROTECTED.get(text)}, but a ${kind} is expected here.`);
+    }
+    seen.push(text);
+    const entry = { protectedB64: s.protected, signature: fromBase64url(s.signature) };
+    if (expected.passkey) {
+      exactMembers(s.header, ['authenticatorData', 'clientDataJSON'], 'The "header" of a passkey signature');
+      entry.header = s.header;
+    }
+    signatures.push(entry);
+  }
+  if (seen.length !== expected.protected.length || seen.some((text, i) => text !== expected.protected[i])) {
+    throw new Refusal(
+      'bad-signatures-layout',
+      expected.passkey
+        ? `A ${kind} carries exactly one signature.`
+        : kind === 'seal'
+          ? 'A seal carries exactly three signatures: Ed25519, ML-DSA-87, then SLH-DSA-SHA2-256s.'
+          : `A ${kind} carries exactly two signatures: Ed25519, then ML-DSA-87.`,
+    );
+  }
+
+  const contentBytes = fromBase64url(record.payload);
+  const content = parseCanonical(fromUtf8(contentBytes, 'payload-not-canonical'));
+  if (content === null || typeof content !== 'object' || Array.isArray(content)) {
+    throw new Refusal('bad-field', 'The content must be an object.');
+  }
+  if (content.type !== expected.type) {
+    // Nothing from the content goes into the message: it is untrusted, and need not even be text.
+    throw new Refusal('payload-type-mismatch', `The content does not say it is a ${kind}, which is what is expected here.`);
+  }
+  return {
+    kind,
+    payloadB64: record.payload,
+    contentBytes,
+    content,
+    fingerprint: await fingerprint(contentBytes),
+    signatures,
+  };
+}
+
+/**
+ * Write content in the canonical form and return what a signer needs.
+ * @param {any} content
+ * @returns {{contentBytes: Uint8Array, payloadB64: string}}
+ */
+export function encodeContent(content) {
+  const contentBytes = utf8(canonicalJson(content));
+  return { contentBytes, payloadB64: toBase64url(contentBytes) };
+}

package/src/keys.js

@@ -0,0 +1,149 @@
+// Public keys: the exact shapes the format accepts (format description,
+// section 3.8), their thumbprints (RFC 7638) and how each is loaded for
+// checking a signature.
+
+import { Refusal, fromBase64url, sha256, toBase64url, utf8 } from './encoding.js';
+
+/** The signing methods of an agent's or a service's key set, in order. */
+export const KEY_SET_METHODS = ['Ed25519', 'ML-DSA-87'];
+
+/**
+ * The signing methods of a recorder's key set, which signs seals, in order.
+ * The third rests only on fingerprint functions (FIPS 205).
+ */
+export const SEAL_METHODS = ['Ed25519', 'ML-DSA-87', 'SLH-DSA-SHA2-256s'];
+
+/** The signing methods a passkey may use. */
+export const PASSKEY_METHODS = ['ES256', 'RS256', 'Ed25519'];
+
+// For each method: the exact members of its JSON Web Key, in sorted order.
+const SHAPES = {
+  Ed25519: ['alg', 'crv', 'kty', 'x'],
+  'ML-DSA-87': ['alg', 'kty', 'pub'],
+  'SLH-DSA-SHA2-256s': ['alg', 'kty', 'pub'],
+  ES256: ['alg', 'crv', 'kty', 'x', 'y'],
+  RS256: ['alg', 'e', 'kty', 'n'],
+};
+
+function bad(where, why) {
+  return new Refusal('bad-key', `${where}: ${why}`);
+}
+
+function bytesOf(jwk, member, where) {
+  try {
+    return fromBase64url(jwk[member]);
+  } catch {
+    throw bad(where, `"${member}" is not base64url.`);
+  }
+}
+
+/**
+ * Confirm that a key is exactly one of the accepted shapes.
+ * @param {any} jwk
+ * @param {string[]} allowed the methods allowed in this place
+ * @param {string} where which key, for the message
+ * @returns {string} the key's method
+ */
+export function checkKey(jwk, allowed, where) {
+  if (jwk === null || typeof jwk !== 'object' || Array.isArray(jwk)) throw bad(where, 'a key must be an object.');
+  const alg = jwk.alg;
+  if (typeof alg !== 'string' || !allowed.includes(alg) || !Object.hasOwn(SHAPES, alg)) {
+    throw bad(where, `the signing method must be one of ${allowed.join(', ')}.`);
+  }
+  const names = Object.keys(jwk).sort();
+  const expected = SHAPES[alg];
+  if (names.length !== expected.length || names.some((n, i) => n !== expected[i])) {
+    throw bad(where, `a ${alg} key must hold exactly ${expected.join(', ')}.`);
+  }
+  for (const n of names) {
+    if (typeof jwk[n] !== 'string') throw bad(where, `"${n}" must be text.`);
+  }
+  if (alg === 'Ed25519') {
+    if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519') throw bad(where, 'an Ed25519 key has kty OKP and crv Ed25519.');
+    if (bytesOf(jwk, 'x', where).length !== 32) throw bad(where, 'an Ed25519 public key is 32 bytes.');
+  } else if (alg === 'ML-DSA-87') {
+    if (jwk.kty !== 'AKP') throw bad(where, 'an ML-DSA-87 key has kty AKP.');
+    // FIPS 204, table 2: an ML-DSA-87 public key is 2,592 bytes.
+    if (bytesOf(jwk, 'pub', where).length !== 2592) throw bad(where, 'an ML-DSA-87 public key is 2,592 bytes.');
+  } else if (alg === 'SLH-DSA-SHA2-256s') {
+    if (jwk.kty !== 'AKP') throw bad(where, 'an SLH-DSA key has kty AKP.');
+    // FIPS 205, table 2: an SLH-DSA-SHA2-256s public key is 64 bytes.
+    if (bytesOf(jwk, 'pub', where).length !== 64) throw bad(where, 'an SLH-DSA-SHA2-256s public key is 64 bytes.');
+  } else if (alg === 'ES256') {
+    if (jwk.kty !== 'EC' || jwk.crv !== 'P-256') throw bad(where, 'an ES256 key has kty EC and crv P-256.');
+    if (bytesOf(jwk, 'x', where).length !== 32 || bytesOf(jwk, 'y', where).length !== 32) {
+      throw bad(where, 'the two halves of a P-256 public key are 32 bytes each.');
+    }
+  } else {
+    if (jwk.kty !== 'RSA' || jwk.e !== 'AQAB') throw bad(where, 'an RS256 key has kty RSA and e AQAB.');
+    const n = bytesOf(jwk, 'n', where);
+    // The size in bits: whole bytes after the first, and the bits of the first.
+    const bits = n.length === 0 || n[0] === 0 ? 0 : (n.length - 1) * 8 + (32 - Math.clz32(n[0]));
+    if (bits < 2048 || bits > 8192) throw bad(where, 'an RS256 key is 2,048 to 8,192 bits.');
+  }
+  return alg;
+}
+
+/**
+ * Confirm that a value is a key set: exactly an Ed25519 key, then an
+ * ML-DSA-87 key (format description, section 3.9).
+ * @param {any} keys
+ * @param {string} where
+ */
+export function checkKeySet(keys, where) {
+  if (!Array.isArray(keys) || keys.length !== KEY_SET_METHODS.length) {
+    throw bad(where, 'a key set is exactly two keys: Ed25519, then ML-DSA-87.');
+  }
+  KEY_SET_METHODS.forEach((alg, i) => checkKey(keys[i], [alg], `${where}[${i}]`));
+}
+
+/**
+ * Confirm that a value is a recorder's key set: exactly an Ed25519 key, an
+ * ML-DSA-87 key and an SLH-DSA-SHA2-256s key, in that order.
+ * @param {any} keys
+ * @param {string} where
+ */
+export function checkSealKeySet(keys, where) {
+  if (!Array.isArray(keys) || keys.length !== SEAL_METHODS.length) {
+    throw bad(where, 'a recorder\'s key set is exactly three keys: Ed25519, ML-DSA-87, then SLH-DSA-SHA2-256s.');
+  }
+  SEAL_METHODS.forEach((alg, i) => checkKey(keys[i], [alg], `${where}[${i}]`));
+}
+
+/**
+ * The thumbprint of a key: RFC 7638 with SHA-256. The members used are those
+ * RFC 7638 section 3.2 names, and for ML-DSA those RFC 9964 section 6 names.
+ * The key must already have passed checkKey, so its members are exactly the
+ * required ones, already known to be plain base64url text.
+ * @param {any} jwk
+ * @returns {Promise<string>}
+ */
+export async function thumbprint(jwk) {
+  const required = { ...jwk };
+  // "alg" is part of the thumbprint only for the AKP key type.
+  if (jwk.kty !== 'AKP') delete required.alg;
+  const names = Object.keys(required).sort();
+  const text = '{' + names.map((n) => JSON.stringify(n) + ':' + JSON.stringify(required[n])).join(',') + '}';
+  return toBase64url(await sha256(utf8(text)));
+}
+
+/**
+ * Load a public key for checking signatures.
+ * @param {any} jwk a key that has passed checkKey
+ * @returns {Promise<CryptoKey>}
+ */
+export function importPublicKey(jwk) {
+  const subtle = globalThis.crypto.subtle;
+  switch (jwk.alg) {
+    case 'Ed25519':
+      return subtle.importKey('jwk', { kty: 'OKP', crv: 'Ed25519', x: jwk.x }, { name: 'Ed25519' }, false, ['verify']);
+    case 'ML-DSA-87':
+      return subtle.importKey('jwk', { kty: 'AKP', alg: 'ML-DSA-87', pub: jwk.pub }, { name: 'ML-DSA-87' }, false, ['verify']);
+    case 'ES256':
+      return subtle.importKey('jwk', { kty: 'EC', crv: 'P-256', x: jwk.x, y: jwk.y }, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']);
+    case 'RS256':
+      return subtle.importKey('jwk', { kty: 'RSA', n: jwk.n, e: jwk.e }, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['verify']);
+    default:
+      return Promise.reject(new Error('unknown signing method'));
+  }
+}

package/src/pass.js

@@ -0,0 +1,67 @@
+// Passing a slip on: an agent hands part of its permission to a helper
+// agent. Format description, section 25.
+
+import { formatTime, randomId } from './encoding.js';
+import * as f from './fields.js';
+import { KINDS } from './jws.js';
+import { checkKeySet } from './keys.js';
+import { validateLimits } from './slip.js';
+import { signWithKeySet } from './stub.js';
+
+/** The most times a slip may let its permission be passed on. */
+export const MAX_PASSES = 10;
+
+/**
+ * Confirm every member of a pass's content.
+ * @param {any} c
+ */
+export function validatePassContent(c) {
+  f.members(c, ['actions', 'id', 'limits', 'slip', 'to', 'type', 'validFrom', 'validUntil', 'when'], ['from'], 'pass');
+  f.id(c.id, 'id');
+  f.fingerprintText(c.slip, 'slip');
+  if (Object.hasOwn(c, 'from')) f.fingerprintText(c.from, 'from');
+  f.members(c.to, ['keys', 'name'], [], 'to');
+  f.label(c.to.name, 'to.name');
+  checkKeySet(c.to.keys, 'to.keys');
+  f.list(c.actions, 1, 64, 'actions');
+  c.actions.forEach((a, i) => f.actionName(a, `actions[${i}]`));
+  if (new Set(c.actions).size !== c.actions.length) throw f.fail('actions', 'an action name is repeated.');
+  validateLimits(c.actions, c.limits);
+  const from = f.time(c.validFrom, 'validFrom');
+  const until = f.time(c.validUntil, 'validUntil');
+  if (!(from < until)) throw f.fail('validUntil', 'must be later than validFrom.');
+  f.time(c.when, 'when');
+}
+
+/**
+ * Write and sign a pass: the agent that holds a permission hands part of it
+ * to a helper agent.
+ *
+ * @param {object} fields
+ * @param {string} fields.slip the fingerprint of the slip
+ * @param {string} [fields.from] the fingerprint of the pass the signer itself acts under; absent when the signer is the slip's own agent
+ * @param {{keys: object[], name: string}} fields.to the helper agent's public key set and its name (a label)
+ * @param {string[]} fields.actions what the helper may do: no more than the signer may
+ * @param {object[]} [fields.limits] limits for the helper, in the form a slip uses
+ * @param {string} fields.validFrom
+ * @param {string} fields.validUntil
+ * @param {number|Date} [fields.when] defaults to now
+ * @param {CryptoKey[]} privateKeys the private keys of the agent that passes on: Ed25519, then ML-DSA-87
+ * @returns {Promise<{record: object, fingerprint: string}>}
+ */
+export async function writePass(fields, privateKeys) {
+  const content = {
+    type: KINDS.pass.type,
+    id: fields.id ?? randomId(),
+    slip: fields.slip,
+    to: fields.to,
+    actions: fields.actions,
+    limits: fields.limits ?? [],
+    validFrom: fields.validFrom,
+    validUntil: fields.validUntil,
+    when: formatTime(fields.when ?? Date.now()),
+  };
+  if (fields.from) content.from = fields.from;
+  validatePassContent(content);
+  return signWithKeySet('pass', content, privateKeys);
+}

package/src/passkey-browser.d.ts

@@ -0,0 +1,20 @@
+// Type declarations for the part of the library that asks a browser's
+// passkey to sign. See types.d.ts.
+import type { Assertion, Base64url, PasskeyKey, Request, SignedRecord, SlipFields, Fingerprint } from './types.js';
+
+export class PasskeyError extends Error {
+  code: string;
+}
+/** What must be kept to sign later: the passkey's identifier, its public key, and the website. */
+export interface StoredPasskey {
+  credentialId: string;
+  key: PasskeyKey;
+  rpId: string;
+  origin: string;
+}
+export function createPasskey(o: { name: string; site: string }): Promise<StoredPasskey>;
+export function signSlipWithPasskey(fields: Omit<SlipFields, 'issuer'>, passkey: StoredPasskey, issuerName: string): Promise<SignedRecord>;
+export function approveWithPasskey(request: Request & { slip: Fingerprint; when?: number | Date }, passkey: StoredPasskey): Promise<SignedRecord>;
+export function cancelWithPasskey(request: { slip: Fingerprint; when?: number | Date; id?: Base64url }, passkey: StoredPasskey): Promise<SignedRecord>;
+/** Sign the challenge of anything prepared for a passkey; hand the result to the matching assemble function. */
+export function signChallengeWithPasskey(challenge: Uint8Array, passkey: StoredPasskey): Promise<Assertion>;

package/src/passkey-browser.js

@@ -0,0 +1,171 @@
+// Signing a slip with a passkey, in a browser. This is the only file that
+// touches the page: it calls the browser's Web Authentication interface.
+//
+// Format description, section 4.2.
+
+import { toBase64url, fromBase64url } from './encoding.js';
+import { assembleApproval, prepareApproval } from './approval.js';
+import { assembleSlip, prepareSlip } from './slip.js';
+import { assembleCancellation, prepareCancellation } from './standing.js';
+
+/** A plain reason a passkey step could not be done, with a code a page can act on. */
+export class PasskeyError extends Error {
+  /** @param {'unavailable'|'cancelled'|'unsupported-key'} code @param {string} message */
+  constructor(code, message) {
+    super(message);
+    this.name = 'PasskeyError';
+    this.code = code;
+  }
+}
+
+function credentials() {
+  if (!globalThis.isSecureContext || !globalThis.navigator || !navigator.credentials || !globalThis.PublicKeyCredential) {
+    throw new PasskeyError('unavailable', 'This browser cannot use passkeys on this page.');
+  }
+  return navigator.credentials;
+}
+
+// The signing methods asked for, in order of preference, by their numbers
+// in the COSE registry: ES256 (-7), Ed25519 (-8), RS256 (-257).
+const METHODS = [
+  { type: 'public-key', alg: -7 },
+  { type: 'public-key', alg: -8 },
+  { type: 'public-key', alg: -257 },
+];
+
+async function publicKeyToJwk(spki, coseAlg) {
+  const subtle = crypto.subtle;
+  if (coseAlg === -7) {
+    const key = await subtle.importKey('spki', spki, { name: 'ECDSA', namedCurve: 'P-256' }, true, ['verify']);
+    const jwk = await subtle.exportKey('jwk', key);
+    return { alg: 'ES256', crv: 'P-256', kty: 'EC', x: jwk.x, y: jwk.y };
+  }
+  if (coseAlg === -257) {
+    const key = await subtle.importKey('spki', spki, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, true, ['verify']);
+    const jwk = await subtle.exportKey('jwk', key);
+    return { alg: 'RS256', e: jwk.e, kty: 'RSA', n: jwk.n };
+  }
+  if (coseAlg === -8) {
+    const key = await subtle.importKey('spki', spki, { name: 'Ed25519' }, true, ['verify']);
+    const jwk = await subtle.exportKey('jwk', key);
+    return { alg: 'Ed25519', crv: 'Ed25519', kty: 'OKP', x: jwk.x };
+  }
+  throw new PasskeyError('unsupported-key', 'The passkey uses a signing method this format does not accept.');
+}
+
+/**
+ * Make a new passkey on this device for this website.
+ *
+ * @param {object} who
+ * @param {string} who.name the person's name, shown by the device when it asks
+ * @param {string} who.site a name for this website, shown by the device
+ * @returns {Promise<{credentialId: string, key: object, rpId: string, origin: string}>}
+ *   what must be kept to sign slips later: the passkey's identifier, its public key, and the website
+ */
+export async function createPasskey({ name, site }) {
+  const container = credentials();
+  let credential;
+  try {
+    credential = await container.create({
+      publicKey: {
+        rp: { id: location.hostname, name: site },
+        user: { id: crypto.getRandomValues(new Uint8Array(16)), name, displayName: name },
+        challenge: crypto.getRandomValues(new Uint8Array(32)),
+        pubKeyCredParams: METHODS,
+        authenticatorSelection: { residentKey: 'preferred', userVerification: 'required' },
+        attestation: 'none',
+      },
+    });
+  } catch (e) {
+    throw new PasskeyError('cancelled', 'The passkey was not made. The request was cancelled or the device refused it.');
+  }
+  const response = credential.response;
+  const spki = response.getPublicKey();
+  if (!spki) throw new PasskeyError('unsupported-key', 'The device did not give the passkey\'s public key.');
+  const key = await publicKeyToJwk(spki, response.getPublicKeyAlgorithm());
+  return { credentialId: toBase64url(new Uint8Array(credential.rawId)), key, rpId: location.hostname, origin: location.origin };
+}
+
+// Ask the passkey to sign a challenge: the device asks the person first.
+async function signedBy(passkey, challenge, refused) {
+  const container = credentials();
+  let assertion;
+  try {
+    assertion = await container.get({
+      publicKey: {
+        challenge,
+        rpId: passkey.rpId,
+        allowCredentials: [{ type: 'public-key', id: fromBase64url(passkey.credentialId) }],
+        userVerification: 'required',
+      },
+    });
+  } catch (e) {
+    throw new PasskeyError('cancelled', refused);
+  }
+  const r = assertion.response;
+  return {
+    authenticatorData: new Uint8Array(r.authenticatorData),
+    clientDataJSON: new Uint8Array(r.clientDataJSON),
+    signature: new Uint8Array(r.signature),
+  };
+}
+
+/**
+ * Sign a slip with a passkey made by createPasskey.
+ *
+ * @param {object} fields the slip's members except "type", "id" and "issuer"
+ * @param {object} passkey what createPasskey returned
+ * @param {string} issuerName the label to write as the issuer's name
+ * @returns {Promise<object>} the signed slip record
+ */
+export async function signSlipWithPasskey(fields, passkey, issuerName) {
+  credentials();
+  const prepared = await prepareSlip({
+    ...fields,
+    issuer: { name: issuerName, key: passkey.key, rpId: passkey.rpId, origin: passkey.origin },
+  });
+  return assembleSlip(prepared, await signedBy(passkey, prepared.challenge, 'The slip was not signed. The request was cancelled or the device refused it.'));
+}
+
+/**
+ * Approve one action with a passkey made by createPasskey: the person's own
+ * yes, signed with the same passkey as the slip.
+ *
+ * @param {object} request what prepareApproval takes: the slip's fingerprint, the action, and where present the amount, the service, the documents and the time
+ * @param {object} passkey what createPasskey returned
+ * @returns {Promise<object>} the signed approval record
+ */
+export async function approveWithPasskey(request, passkey) {
+  credentials();
+  const prepared = await prepareApproval(request);
+  return assembleApproval(prepared, await signedBy(passkey, prepared.challenge, 'The action was not approved. The request was cancelled or the device refused it.'));
+}
+
+/**
+ * Cancel a slip with the passkey that signed it, made by createPasskey.
+ * Keep a copy of what this returns, with its time-stamps: it counts even
+ * where whoever keeps the book leaves it out.
+ *
+ * @param {object} request what prepareCancellation takes: the slip's fingerprint, and where present the time
+ * @param {object} passkey what createPasskey returned
+ * @returns {Promise<object>} the signed cancellation record
+ */
+export async function cancelWithPasskey(request, passkey) {
+  credentials();
+  const prepared = await prepareCancellation(request);
+  return assembleCancellation(prepared, await signedBy(passkey, prepared.challenge, 'The slip was not cancelled. The request was cancelled or the device refused it.'));
+}
+
+/**
+ * Sign the challenge of anything prepared for a passkey (prepareSlip with
+ * covered fields, for one) with a passkey made by createPasskey. Hand what
+ * this returns to the matching assemble function.
+ *
+ * @param {Uint8Array} challenge the "challenge" of what was prepared
+ * @param {object} passkey what createPasskey returned
+ * @returns {Promise<{authenticatorData: Uint8Array, clientDataJSON: Uint8Array, signature: Uint8Array}>}
+ */
+export async function signChallengeWithPasskey(challenge, passkey) {
+  credentials();
+  return signedBy(passkey, challenge, 'Nothing was signed. The request was cancelled or the device refused it.');
+}