@bakobo/fiki 0.0.1 → 0.7.0

package/README.md

@@ -1,3 +1,72 @@
-# fiki (placeholder)
+# fiki (JavaScript)
 
-Name reserved for fiki: RFC 9421 HTTP message signatures with an Ed25519 key or a KERI AID as the identifier. This 0.0.1 is an empty placeholder; the first real release follows. Source: https://github.com/bakobo/fiki
+[![JavaScript](https://github.com/bakobo/fiki/actions/workflows/ci-js.yml/badge.svg)](https://github.com/bakobo/fiki/actions/workflows/ci-js.yml)
+
+The JavaScript implementation of [fiki](../README.md). Runs in browsers and in Node 20 or newer, with **no dependencies at all** — Ed25519, SHA-256 and randomness come from WebCrypto, and the RFC 8941 structured-fields subset RFC 9421 needs is a few hundred lines in `src/sfv.js`.
+
+## From a fresh clone to passing tests
+
+```sh
+cd js
+npm test
+```
+
+There is nothing to install. The suite runs under `node:test`, and `npm run test:coverage` adds the same 100% branch gate the Python port holds — separately, because Node's coverage thresholds need 22 or newer while the library itself runs on 20. Both commands run the shared `vectors/` at the repository root, so this implementation and the Python one are held to the same bytes.
+
+## Signing a request
+
+```js
+import { Key, signRequest } from '@bakobo/fiki';
+
+const key = await Key.generate();          // non-extractable; see below
+console.log(key.aid);                      // register this once with whoever you call
+
+const url = 'https://api.example.com/things?limit=1';
+const body = new TextEncoder().encode(JSON.stringify({ hello: 'world' }));
+
+const signed = await signRequest({ key, method: 'POST', url, body });
+await fetch(url, { method: 'POST', body, headers: signed });
+```
+
+By default the signature binds the method, the host, the path, the query string, and a digest of the body. Pass the body wherever you pass the URL: fiki covers a body it is given, or refuses to sign — but it cannot cover one it never sees.
+
+## Verifying a request
+
+```js
+import { verifyRequest } from '@bakobo/fiki';
+
+const { aid, covered } = await verifyRequest({
+  method: request.method,
+  url: request.url,          // a full URL, or a path plus a Host header
+  headers: request.headers,
+  body: await request.bytes(),
+  maxAge: 300,               // seconds, or null to decline the check
+});
+```
+
+`maxAge` has no default and must be given. Both defaults would be wrong: a number guesses at somebody else's clock skew and replay window, and skipping the check silently is the thing the argument exists to prevent. An `expires` the signer declared is enforced either way.
+
+## Keys in a browser
+
+`Key.generate()` returns a **non-extractable** key: JavaScript cannot read its private half, so an XSS bug cannot exfiltrate it. Store the object itself in IndexedDB, which persists a `CryptoKey` without ever exposing the bytes. The cost is that the identity belongs to that browser profile — a new device registers a new AID, and `key.seed` throws.
+
+When an identity has to outlive the profile, ask for it:
+
+```js
+const key = await Key.generate({ extractable: true });
+await save(key.seed);                      // 32 bytes, and now your problem to protect
+const same = await Key.fromSeed(await load());
+```
+
+The safe shape is the default and the portable one is explicit, because the two runtimes have genuinely different threat models and a browser should not inherit a server's.
+
+## Differences from the Python port
+
+Everything is async. WebCrypto's `sign`, `verify`, `digest` and `importKey` all return promises, so `signRequest`, `signResponse`, `verifyRequest`, `verifyResponse` and the `Key` constructors do too, where the Python versions are synchronous. Names are otherwise the same in camelCase — `signatureBase`, `responseSignatureBase`, `verifyingKey`, `Key.fromSeed`, `key.aid`, `expectedKeyid` — so the two read as one library. Four more differences are deliberate (`this.i` @9enyfktu):
+
+- A `resolve` function may return the key or a promise of it, and verification awaits either, because a KERI resolver usually reads key state from storage or a network.
+- The request a response answers is a plain object, `{ method, url, headers, body }`, rather than an exported `Request` class.
+- A mistake in the call rather than the message — `expectedAid` together with `resolve`, a `minimum` smaller than the profile's, a missing `maxAge`, a response binding the request's digest verified without the request body — is a `TypeError`. Python raises `TypeError` for some of these and `ValueError` for others; JavaScript has no `ValueError`. None of them is a `FikiError`.
+- `KERI_VECTORS_FORMAT` is exported beside `VECTORS_FORMAT`, so the KERI profile's contract (`vectors/keri/`) can be read the same way as the shared one.
+
+URLs are split as sent, as Python's `urlsplit` does, rather than parsed with `new URL`, which normalizes the path that RFC 9421 and the KERI profile sign unnormalized (`this.i` @90y0gsfx).

package/package.json

@@ -1,9 +1,37 @@
 {
   "name": "@bakobo/fiki",
-  "version": "0.0.1",
-  "description": "Name reserved for fiki (RFC 9421 HTTP message signatures). Empty placeholder; see the repository.",
+  "version": "0.7.0",
+  "description": "Sign and verify HTTP requests with a bare Ed25519 key as the identifier. Standard RFC 9421, no KERI dependencies.",
+  "keywords": [
+    "rfc9421",
+    "http-message-signatures",
+    "ed25519",
+    "keri",
+    "aid"
+  ],
   "license": "Apache-2.0",
+  "author": "Bakobo",
   "homepage": "https://github.com/bakobo/fiki",
-  "repository": { "type": "git", "url": "git+https://github.com/bakobo/fiki.git" },
-  "files": ["README.md"]
+  "bugs": {
+    "url": "https://github.com/bakobo/fiki/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bakobo/fiki.git",
+    "directory": "js"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-branches=100 --test-coverage-lines=100 --test-coverage-functions=100 --test-coverage-exclude='test/**'"
+  }
 }

package/src/base.js

@@ -0,0 +1,325 @@
+// The RFC 9421 signature base, section 2.5 (`this.i` @2hwvpm42, @2q9gv70t, @7f28p7xk).
+//
+// Public surface, not an internal detail. When two implementations disagree about a signature,
+// the base is where they disagree, and a caller debugging an interop failure needs to see the
+// bytes both sides actually hashed.
+//
+// Derived components fiki builds: @method, @authority, @path, @query in a request, and @status in
+// a response, which may also name its request's components with the `req` parameter of section
+// 2.4. Anything else raises rather than being skipped — a component silently dropped from the base
+// is a component the caller believes is covered and is not.
+
+import { utf8 } from './bytes.js';
+import { DuplicateComponent, MissingComponent, SignatureMismatch, UnsupportedComponent } from './errors.js';
+import { parseItem, serializeInnerList, serializeItem } from './sfv.js';
+
+export const DERIVED = ['@method', '@authority', '@path', '@query'];
+
+// The one derived component a response has of its own (RFC 9421 section 2.2.9). Every request
+// component reaches a response only through `req`.
+export const RESPONSE_DERIVED = ['@status'];
+
+// @method, @authority, @path, @query — plus content-digest whenever there is a body (@2hwvpm42).
+// This closes the query, host, and body gaps that heti's KERI dialect leaves open and
+// structurally cannot close. `created` is a signature parameter rather than a component.
+export const DEFAULT_COVERED = ['@method', '@authority', '@path', '@query'];
+
+export const CONTENT_DIGEST = 'content-digest';
+
+// The only component parameter fiki supports, and only in a response (RFC 9421 section 2.4).
+const REQ = 'req';
+
+// Order is the signer's choice — a verifier reserializes whatever it received — so fiki fixes one
+// order and keeps it, which makes its own output reproducible.
+const PARAM_ORDER = ['created', 'expires', 'nonce', 'alg', 'keyid', 'tag'];
+
+// A Map, because it is keyed by the caller's scheme, and an object literal would answer
+// "constructor" from Object.prototype (Copilot review of PR #5, C4).
+const DEFAULT_PORTS = new Map([
+  ['http', '80'],
+  ['https', '443'],
+  ['ws', '80'],
+  ['wss', '443'],
+]);
+
+/** A component identifier from a caller's spelling of it.
+ *
+ * A plain name (`"@method"`, `"Content-Digest"`) or its RFC 8941 serialization with parameters
+ * (`'"@method";req'`). Names are lowercased as a convenience to a local caller; a name parsed from
+ * the wire is never lowercased, and is refused instead when it is not already.
+ */
+export function component(spec) {
+  if (!spec.startsWith('"')) return { value: spec.toLowerCase(), params: new Map() };
+  let item;
+  try {
+    item = parseItem(spec);
+  } catch {
+    item = null;
+  }
+  // A spec that opens with a quote can only parse as a string, so the parse is the whole test.
+  if (item === null) {
+    throw new UnsupportedComponent(
+      `fiki cannot read ${spec} as a component identifier; name a component plainly, as "@path", ` +
+        `or in its serialized form, as '"@path";req'.`,
+      { component: spec, supported: [...DERIVED, ...RESPONSE_DERIVED].join(', ') },
+    );
+  }
+  return { value: item.value.toLowerCase(), params: item.params };
+}
+
+/** The spelling of a request component named from a response: `req('@path')` is `'"@path";req'`. */
+export const req = (name) => serializeItem({ value: name.toLowerCase(), params: new Map([[REQ, true]]) });
+
+/** The inverse of `component`: a plain name when it has no parameters. */
+export const specOf = (item) => (item.params.size > 0 ? serializeItem(item) : item.value);
+
+/** What two identifiers must share to be the same component. Parameter order is not it. */
+export const identity = (item) => serializeItem({ value: item.value, params: new Map([...item.params].sort()) });
+
+/** Refuse a covered list fiki cannot build faithfully: duplicates first, then the unsupported.
+ *
+ * That order is the KERI profile's section 9, so a list that is both has one correct refusal.
+ */
+export function checkCovered(items, { response }) {
+  const seen = new Set();
+  for (const item of items) {
+    if (seen.has(identity(item))) {
+      throw new DuplicateComponent(
+        `The covered components name ${specOf(item)} twice, so the signature base would not be ` +
+          'what either copy says it is.',
+        { component: specOf(item) },
+      );
+    }
+    seen.add(identity(item));
+  }
+
+  for (const item of items) {
+    const isReq = item.params.get(REQ) === true;
+    const others = [...item.params.keys()].some((name) => name !== REQ);
+    if (others || (item.params.has(REQ) && !(isReq && response))) {
+      throw new UnsupportedComponent(
+        `fiki does not support the component ${specOf(item)}: the only component parameter it ` +
+          `supports is "${REQ}", and only in a response.`,
+        { component: specOf(item), supported: REQ },
+      );
+    }
+    if (item.value.startsWith('@')) {
+      const supported = isReq || !response ? DERIVED : RESPONSE_DERIVED;
+      if (!supported.includes(item.value)) {
+        throw new UnsupportedComponent(
+          `fiki does not build the derived component ${specOf(item)} in a ` +
+            `${response ? 'response' : 'request'}; it builds ${supported.join(', ')}.`,
+          { component: specOf(item), supported: supported.join(', ') },
+        );
+      }
+    }
+  }
+}
+
+/** A URL split as sent, per RFC 3986 section 3, with nothing decoded or normalized.
+ *
+ * Not `new URL`, which follows the WHATWG URL standard: it resolves dot segments and
+ * percent-encodes characters such as a space, so its pathname is not the path that was sent. The
+ * KERI profile requires @path "in its encoded form, percent-encoding included and unnormalized"
+ * (section 2), and so does RFC 9421 section 2.2.6, which is what fiki-py's urlsplit gives.
+ */
+export function splitUrl(url) {
+  const match = /^(?:([A-Za-z][A-Za-z0-9+.-]*):)?(?:\/\/([^/?#]*))?([^?#]*)(?:\?([^#]*))?/.exec(url);
+  const [, scheme = '', netloc, path, query = ''] = match;
+  return { scheme: scheme.toLowerCase(), netloc: netloc ?? '', path, query };
+}
+
+function authority(parts, headers) {
+  // RFC 9421 section 2.2.3: lowercase host, default port omitted. A relative URL falls back to the
+  // Host header, which in HTTP/1.1 *is* the authority — the shape a server-side verifier actually
+  // holds. Nothing is normalized away there, because without a scheme no port is a default port.
+  if (parts.netloc) {
+    const hostport = parts.netloc.slice(parts.netloc.lastIndexOf('@') + 1).toLowerCase();
+    const [, host, port = ''] = /^(\[[^\]]*\]|[^:]*)(?::(.*))?$/.exec(hostport);
+    if (port === '') return host;
+    // RFC 3986 section 3.2.3: port = *DIGIT, so any run of ASCII digits, leading zeros and all, and
+    // the value is the number: "000080" is 80 and is the default, as urlsplit reads it. The range
+    // is checked on the digits that remain, so a long run of zeros cannot hide an overflow.
+    const digits = /^[0-9]+$/.test(port) ? port.replace(/^0+(?=[0-9])/, '') : null;
+    if (digits === null || digits.length > 5 || Number(digits) > 65535) {
+      throw new TypeError(`The URL's port "${port}" is not a port number between 0 and 65535.`);
+    }
+    if (digits === DEFAULT_PORTS.get(parts.scheme)) return host;
+    return `${host}:${digits}`;
+  }
+  const host = headers.get('host');
+  if (host === undefined) {
+    throw new MissingComponent(
+      'The signature covers "@authority", but the URL carries no authority and the request has ' +
+        'no Host header, so there is nothing to derive it from.',
+      { component: '@authority' },
+    );
+  }
+  return ows(checked(host, '"@authority"')).toLowerCase();
+}
+
+/** Headers with every name lowercased, refusing two names that are one field (D-Q9ZT).
+ *
+ * Field names are case-insensitive, so `X-Role` beside `x-role` is two values for one field, and
+ * keeping either would let a signer cover one while the application reads the other. Only a caller
+ * can build such an object, so it is a TypeError. Values are kept exactly as given.
+ */
+export function canonicalHeaders(headers, name = 'headers') {
+  // Null-prototype, so a field named "__proto__" is an own property like any other rather than an
+  // assignment to the prototype that silently drops it (PR #5 hostile review, H1).
+  const out = Object.create(null);
+  for (const [field, value] of Object.entries(headers ?? {})) {
+    const lower = field.toLowerCase();
+    if (Object.hasOwn(out, lower)) {
+      throw new TypeError(
+        `${name} names the field "${lower}" twice in different case, so it holds two values for one ` +
+          'field; pass one.',
+      );
+    }
+    out[lower] = value;
+  }
+  return out;
+}
+
+function lowered(headers) {
+  // Header field names are case-insensitive and appear lowercased in the base (section 2.1). Values
+  // are kept exactly as received here: they are checked for forbidden characters before any
+  // whitespace is trimmed, or a trailing CR LF would be trimmed into the value that was signed.
+  const map = new Map();
+  for (const [name, value] of Object.entries(canonicalHeaders(headers))) map.set(name, String(value));
+  return map;
+}
+
+// Leading and trailing field whitespace, which RFC 9110 section 5.5 defines as SP and HTAB only.
+const ows = (value) => value.replace(/^[ \t]+|[ \t]+$/g, '');
+
+/** A value refused when it has no single serialization both sides agree on.
+ *
+ * A line break inside a value would forge a line of the base, and a byte outside visible ASCII is
+ * encoded differently by different stacks. The KERI profile names such a base unbuildable, and so
+ * a signature mismatch (@2f227n4r).
+ */
+function checked(value, spec) {
+  if (!/^[\t\x20-\x7e]*$/.test(value)) {
+    throw new SignatureMismatch(
+      `The value of ${spec} contains a line break, a control character or a non-ASCII ` +
+        'character, so there is no signature base both sides would build from it.',
+    );
+  }
+  return value;
+}
+
+export function requestMessage(method, url, headers) {
+  // A method is the caller's to supply, and an absent one would otherwise be signed as the string
+  // "undefined". Required here, where every request and every response's request passes.
+  if (typeof method !== 'string' || method === '') {
+    throw new TypeError(`A request needs its method as a non-empty string, as sent; got ${String(method) || 'an empty string'}.`);
+  }
+  return { headers: lowered(headers), method, parts: splitUrl(url) };
+}
+
+export const responseMessage = (status, headers, request) => ({
+  headers: lowered(headers),
+  status,
+  request: request ? requestMessage(request.method, request.url, request.headers) : null,
+});
+
+function componentValue(item, message) {
+  let source = message;
+  if (item.params.get(REQ) === true) {
+    if (message.request === null) {
+      throw new MissingComponent(
+        `The signature covers ${specOf(item)}, which is read from the request this response ` +
+          'answers, and no request was supplied.',
+        { component: specOf(item) },
+      );
+    }
+    source = message.request;
+  }
+  const name = item.value;
+  if (name === '@status') {
+    // Section 2.2.9: the three-digit status code. Anything else is not a status this component
+    // can carry, so there is no value to sign or to check.
+    const { status } = source;
+    if (!Number.isInteger(status) || status < 100 || status > 999) {
+      throw new MissingComponent(
+        `The signature covers @status, and ${String(status)} is not a three-digit HTTP status ` +
+          'code, so there is no status line to build.',
+        { component: '@status' },
+      );
+    }
+    return String(status);
+  }
+  // Section 2.2.1: the method as sent, with no case transformation (@22g0xkr8).
+  if (name === '@method') return source.method;
+  if (name === '@authority') return authority(source.parts, source.headers);
+  // An empty path is the "/" the origin server would have received.
+  if (name === '@path') return source.parts.path || '/';
+  // Section 2.2.7: the whole query string including the leading "?", percent-encoding preserved,
+  // and a bare "?" when the request carries no query at all.
+  if (name === '@query') return `?${source.parts.query}`;
+  const value = source.headers.get(name);
+  if (value === undefined) {
+    throw new MissingComponent(
+      `The signature covers ${specOf(item)}, but the message carries no value for it, so the ` +
+        'signature base cannot be built.',
+      { component: specOf(item) },
+    );
+  }
+  // Checked as received, then trimmed of field whitespace only.
+  return ows(checked(value, specOf(item)));
+}
+
+/** A component's value, refused when it has no single serialization both sides agree on. */
+export const valueOf = (item, message) => checked(componentValue(item, message), specOf(item));
+
+/** Every line of the signature base except the trailing `@signature-params`. */
+export const linesFor = (items, message) => items.map((item) => `${serializeItem(item)}: ${valueOf(item, message)}`);
+
+/** Every line of a request's signature base except the trailing `@signature-params`.
+ *
+ * Split out because the verify side cannot call `signatureBase`: it must reserialize the
+ * parameters exactly as they arrived, in the order they arrived, rather than in fiki's own fixed
+ * order — a verifier that reorders what it received computes a different base and rejects a good
+ * signature.
+ */
+export function componentLines({ method, url, headers, covered }) {
+  const items = covered.map(component);
+  checkCovered(items, { response: false });
+  return linesFor(items, requestMessage(method, url, headers));
+}
+
+/** The whole base for already-checked items: the component lines, then fiki's own parameters. */
+export function finishBase(items, message, values) {
+  const lines = linesFor(items, message);
+  const params = new Map();
+  for (const name of PARAM_ORDER) {
+    if (values[name] !== undefined && values[name] !== null) params.set(name, values[name]);
+  }
+  lines.push(`"@signature-params": ${serializeInnerList({ items, params })}`);
+  return utf8(lines.join('\n'));
+}
+
+/** Build the RFC 9421 signature base for a request.
+ *
+ * Throws DuplicateComponent for a component named twice, UnsupportedComponent for a derived
+ * component outside DERIVED or a component parameter, and MissingComponent for a covered header
+ * the request does not carry.
+ */
+export function signatureBase({ method, url, headers, covered, created, keyid, alg, expires, nonce, tag }) {
+  const items = covered.map(component);
+  checkCovered(items, { response: false });
+  return finishBase(items, requestMessage(method, url, headers), { created, expires, nonce, alg, keyid, tag });
+}
+
+/** Build the RFC 9421 signature base for a response (sections 2.2.9 and 2.4).
+ *
+ * `request` is the request being answered, `{method, url, headers}`, which `req` components are
+ * read from — spelled `req('@path')` or `'"@path";req'`. Without one, a `req` component is a
+ * MissingComponent.
+ */
+export function responseSignatureBase({ status, headers, covered, created, keyid, request, alg, expires, nonce, tag }) {
+  const items = covered.map(component);
+  checkCovered(items, { response: true });
+  return finishBase(items, responseMessage(status, headers, request), { created, expires, nonce, alg, keyid, tag });
+}

package/src/bytes.js

@@ -0,0 +1,32 @@
+// Base64 without Buffer (`this.i` @2q9gv70t).
+//
+// `Buffer` is Node's, and reaching for it is the easiest way to write a "browser" library that
+// only runs on a server. `btoa`/`atob` are in every browser and in Node 20+, so these four
+// functions are the whole of fiki's binary-to-text needs and the port stays honest about its
+// target.
+
+const toBinaryString = (bytes) => {
+  let out = '';
+  // One character at a time rather than String.fromCharCode(...bytes): spreading a large array
+  // into a call blows the argument limit, and a signature base's digest is small but a body is
+  // not, so the shape that works for both is the one to use everywhere.
+  for (const byte of bytes) out += String.fromCharCode(byte);
+  return out;
+};
+
+const fromBinaryString = (text) => Uint8Array.from(text, (char) => char.charCodeAt(0));
+
+export const toBase64 = (bytes) => btoa(toBinaryString(bytes));
+
+export const fromBase64 = (text) => fromBinaryString(atob(text));
+
+export const toBase64Url = (bytes) => toBase64(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+
+export const fromBase64Url = (text) => {
+  const padded = text.replace(/-/g, '+').replace(/_/g, '/');
+  return fromBase64(padded + '='.repeat((4 - (padded.length % 4)) % 4));
+};
+
+export const utf8 = (text) => new TextEncoder().encode(text);
+
+export const equal = (a, b) => a.length === b.length && a.every((byte, i) => byte === b[i]);

package/src/errors.js

@@ -0,0 +1,91 @@
+// fiki's exception taxonomy (`this.i` @8zw78n0v), one class per condition the Python port names.
+//
+// The class NAMES are the contract, not an implementation detail: `refusals.json` records the name
+// fiki raises for each refusal, and this port's vector driver asserts on it. So a port that folds
+// two conditions together fails a vector rather than passing quietly, and heti — which maps these
+// onto its own codes — can be told what happened by a client in any language.
+//
+// The granularity comes from heti's code taxonomy, which distinguishes a missing header from an
+// unparsable one, per header. That was built deliberately so a sender can be told which header to
+// fix rather than handed the pair.
+
+export class FikiError extends Error {
+  constructor(message, fields = {}) {
+    super(message);
+    this.name = new.target.name;
+    Object.assign(this, fields);
+  }
+}
+
+/* --- something the request needs is absent --- */
+
+export class MissingSignature extends FikiError {}
+export class MissingSignatureInput extends FikiError {}
+export class MissingSignatureLabel extends FikiError {}
+export class MissingKey extends FikiError {}
+export class MissingComponent extends FikiError {}
+
+/** A resolver was supplied and does not know the signature's keyid (`this.i` @6g9zjsv9).
+ *
+ * Never answered by decoding the keyid as a key instead: a basic transferable prefix embeds its
+ * inception key, and reading it would accept a key that has been rotated away.
+ */
+export class UnknownKey extends FikiError {}
+
+/** The keyid's key state has no single key that satisfies its threshold alone (@2f227n4r).
+ *
+ * fiki never decides this itself, since it knows nothing of key state: a resolver throws it, and
+ * fiki carries it out unchanged, so the refusal keeps its own class rather than becoming
+ * UnknownKey.
+ */
+export class UnsupportedSigner extends FikiError {}
+
+/** An unsigned 401 answered the request (@2f227n4r).
+ *
+ * A server that refuses a request before it knows which agent it is cannot sign the refusal, so
+ * an unsigned 401 is an authentication failure whose body is not to be trusted, rather than a
+ * response that is missing its signature.
+ */
+export class Unauthenticated extends FikiError {}
+
+/* --- something the request carries cannot be read --- */
+
+export class MalformedSignature extends FikiError {}
+export class MalformedSignatureInput extends FikiError {}
+export class MalformedSignatureLabel extends FikiError {}
+export class MalformedSignatureValue extends FikiError {}
+export class MalformedKey extends FikiError {}
+export class MalformedDigest extends FikiError {}
+
+/* --- fiki understood the request and will not handle it --- */
+
+export class UnsupportedComponent extends FikiError {}
+
+/** The covered list names the same component twice, whatever the order of its parameters. */
+export class DuplicateComponent extends FikiError {}
+
+/** The signature verifies, and covers less than the verifier's stated minimum (@7f28p7xk).
+ *
+ * Includes a message with a body whose `content-digest` is not covered. A signature over too
+ * little is refused even when it is valid, because a valid signature over the wrong things is
+ * exactly what an intermediary wants.
+ */
+export class InsufficientCoverage extends FikiError {}
+export class UnsupportedAlgorithm extends FikiError {}
+
+/** The request carries a body and the covered set does not include `content-digest`.
+ *
+ * Raised at signing time rather than warned about, because a verifier has no way to discover
+ * after the fact that a body was never covered (@2hwvpm42).
+ */
+export class UncoveredBody extends FikiError {}
+
+/* --- the request is signed and a stated policy refuses it anyway (@67shl6c5) --- */
+
+export class SignatureExpired extends FikiError {}
+export class SignatureTooOld extends FikiError {}
+
+/* --- the request was read, and it does not hold up --- */
+
+export class DigestMismatch extends FikiError {}
+export class SignatureMismatch extends FikiError {}

package/src/index.js

@@ -0,0 +1,42 @@
+// fiki — sign and verify HTTP requests with a bare Ed25519 key as the identifier.
+//
+// Standard RFC 9421, with one lens: an Ed25519 public key is rendered as a non-transferable AID
+// (CESR Ed25519N, a 44-character `B…` string), so the identifier is the verifying key and a
+// verifier resolves nothing — unless the caller names another keyid, such as a KERI AID, and
+// supplies the resolver for it (@6g9zjsv9). Zero dependencies; everything cryptographic comes
+// from WebCrypto, which is why the API is async where the Python port's is not (@2q9gv70t).
+
+// The conformance contract this port satisfies (`this.i` @4fhrre0m). Two artifacts interoperate
+// when their declared vectors format matches, whatever their own version numbers say — so this is
+// the number to compare, not the release. Monotonic, because a conformance contract has no
+// meaningful minor: an implementation either satisfies the vectors or it does not.
+export const VECTORS_FORMAT = 1;
+
+// The KERI profile's own conformance contract, vectors/keri/ (`this.i` @8vwrexxc, @9enyfktu). A
+// separate number from VECTORS_FORMAT, because the two sets answer to different authorities and
+// move independently.
+export const KERI_VECTORS_FORMAT = 3;
+
+export * as errors from './errors.js';
+export { FikiError } from './errors.js';
+export { Key, toAid, verifyingKey, verifySignature } from './keys.js';
+export {
+  CONTENT_DIGEST,
+  DEFAULT_COVERED,
+  DERIVED,
+  componentLines,
+  req,
+  responseSignatureBase,
+  signatureBase,
+} from './base.js';
+export {
+  ALG,
+  DEFAULT_SKEW,
+  REQUEST_MINIMUM,
+  RESPONSE_MINIMUM,
+  contentDigest,
+  signRequest,
+  signResponse,
+  verifyRequest,
+  verifyResponse,
+} from './messages.js';