@uwmd/signing 0.1.0

package/README.md

@@ -0,0 +1,190 @@
+# @uwmd/signing
+
+Block, receipt, and module-manifest signatures for
+[UW Markdown](https://uwmd.org) — the implementation of **protocol §V.11**
+([RFC 0010](../../docs/rfcs/0010-signed-blocks.md)) and **§X.1**
+([RFC 0002](../../docs/rfcs/0002-module-signing.md)).
+
+## Why this is a separate package
+
+`@uwmd/core` is deliberately zero-cryptography. Reading, validating, editing,
+and computing over a `.uw.md` file requires no crypto, and the overwhelming
+majority of adopters should never take a crypto dependency to do any of it.
+
+Signed blocks are for the deployments that genuinely need chain of custody:
+regulated lender data rooms, multi-party deal flow where sponsor, lender, and
+appraiser each sign their own sections, and agent-host accountability where a
+signature proves *which* agent instance wrote a block rather than merely what
+the `actor` field claims.
+
+Core owns the normative, crypto-free half — the wire shape (`_meta.signature`)
+and the canonical signing input. This package owns the algorithms. Two seams
+connect them:
+
+```ts
+verifyChain(parsed, { signatureVerifier })   // blocks
+verifyReceipt(receipt, source, { signatureVerifier })  // receipts (RFC 0016)
+```
+
+Without a verifier, core reports signatures as **present and unchecked** —
+never as valid.
+
+## Install
+
+```bash
+npm install @uwmd/signing
+```
+
+Needs Node ≥ 18.4 (Ed25519 in Web Crypto) or a modern browser. `ed25519`,
+`es256`, and `es384` are the admitted algorithms.
+
+## Signing a block
+
+```ts
+import { computeBlockHash, parseUWFile } from '@uwmd/core';
+import { generateSigningKeyPair, signBlock, stampBlockSignature } from '@uwmd/signing';
+
+const { signing, verifying } = await generateSigningKeyPair('ed25519', 'sponsor-2026');
+
+const parsed = parseUWFile(source);
+const block = parsed.sections.rent_roll;
+
+// A block must already carry `content_hash`: a signature over an absent hash
+// commits to nothing, and validates as INT-05.
+const signature = await signBlock(block, signing);
+const signed = stampBlockSignature(block, signature);
+```
+
+`signBlock` does not mutate the block, and `generateSigningKeyPair` is for
+tests and local development — production keys belong in an HSM or cloud KMS
+behind a custom `KeyStore`.
+
+## Verifying
+
+```ts
+import { verifyChain } from '@uwmd/core';
+import { createBlockSignatureVerifier, loadKeyStoreFile } from '@uwmd/signing';
+
+const store = await loadKeyStoreFile('./keystore.json');
+const result = await verifyChain(parsed, {
+  signatureVerifier: createBlockSignatureVerifier(store),
+});
+
+result.signatures_present;   // how many blocks carry a signature
+result.signatures_verified;  // how many actually verified
+```
+
+Or from the CLI:
+
+```bash
+uwmd verify deal.uwx.md --signing --keystore=./keystore.json
+```
+
+### What each code means
+
+| Code | Severity | Trigger |
+|---|---|---|
+| `INT-05` | error | `signature` present with no `content_hash`. |
+| `INT-06` | error | `kid` names a key the store does not hold. |
+| `INT-07` | error | The signature does not verify, the algorithm is unadmitted, or the stamped `content_hash` no longer recomputes. |
+| `INT-08` | warning | The algorithm is in the deployment's deprecation list. |
+
+`INT-06` and `INT-07` are deliberately distinct. "I cannot check this" and
+"this is forged" call for opposite responses — load a key versus reject the
+document — and a verifier that merges them tells an operator to re-sign when
+the real fix is to configure their key store.
+
+## Key store format
+
+Key *distribution* is out of scope: a public key that travels inside the
+document it authenticates proves nothing. The file format below is a
+**reference**, not a normative one — back a `KeyStore` with an HSM and never
+touch it.
+
+```json
+{
+  "keystore_version": "1",
+  "keys": [
+    {
+      "kid": "sponsor-2026",
+      "alg": "ed25519",
+      "public_key_jwk": { "kty": "OKP", "crv": "Ed25519", "x": "..." }
+    },
+    {
+      "kid": "lender-2026",
+      "alg": "es256",
+      "public_key_spki": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..."
+    }
+  ]
+}
+```
+
+Exactly one of `public_key_jwk` / `public_key_spki` per entry. Every key is
+imported eagerly at load time, so a typo fails once, loudly, instead of
+appearing later as a per-block `INT-07` that reads like tampering.
+
+**Rotation** is "issue new blocks under a new `kid` and keep the old key
+loaded". A `kid` names one key and MUST NOT be reused; blocks signed under a
+retired `kid` stay verifiable for as long as the store retains it.
+
+## Module manifests
+
+Module signing (RFC 0002, protocol §X.1) uses the same keys and the same
+verifier. The signed bytes are the RFC 8785 canonical manifest with `signature`
+removed.
+
+```ts
+import { loadModuleManifestAsync } from '@uwmd/core';
+import { createModuleSignatureVerifier, signModule, stampModuleSignature } from '@uwmd/signing';
+
+const signed = stampModuleSignature(
+  manifest,
+  await signModule(manifest, signing, { identity: 'modules@example.org' }),
+);
+
+const result = await loadModuleManifestAsync(signed, {
+  signaturePolicy: 'require',           // or 'verify-if-present' / 'ignore'
+  signatureVerifier: createModuleSignatureVerifier(store),
+});
+```
+
+The three policies are `ignore` (default), `verify-if-present` (an unsigned
+module loads, a broken signature refuses), and `require`. Both checking
+policies refuse when the key store lacks the `kid` — a host that cannot check a
+signature has established nothing about the module.
+
+`identity` is **advisory**. A signature proves the key holder asserted it,
+never that the assertion is true; an `allowedIdentities` allow-list is worth
+only as much as your decision to bind that `kid` to that identity.
+
+## Receipts
+
+Receipt signing (RFC 0016) uses the same keys:
+
+```ts
+import { verifyReceipt } from '@uwmd/core';
+import { createReceiptSignatureVerifier, signReceipt, stampReceiptSignature } from '@uwmd/signing';
+
+const signed = stampReceiptSignature(receipt, await signReceipt(receipt, signing));
+
+const verdict = await verifyReceipt(signed, source, {
+  signatureVerifier: createReceiptSignatureVerifier(store),
+});
+```
+
+Without a verifier, a signed receipt verifies as `unverifiable` with `RCP-08`.
+
+## Limits
+
+- **`signed_at` is self-asserted.** Audit-grade non-repudiation needs a
+  timestamping authority countersignature, which protocol 1.x does not define.
+- **No selective disclosure.** Signing a redacted block would need Merkle
+  commitments over fields; the current design has none.
+- **Re-rooting a chain requires re-signing.** `content_hash` covers `_meta`,
+  and `parent_hash` lives there — see the erratum in RFC 0010.
+- **No Sigstore.** Keyless signing needs a Fulcio trust root and a Rekor
+  inclusion proof — a vendored snapshot that fails closed when stale, or
+  network access at verify time. `scheme: "sigstore"` is reserved in §X.1.2 so
+  adding it later stays additive.
+
+MIT. Part of the [UW Markdown](https://github.com/UWMD-OSP/UW-Markdown) monorepo.

package/dist/algorithms.d.ts

@@ -0,0 +1,21 @@
+import type { UWSignatureAlgorithm } from '@uwmd/core';
+export interface AlgorithmParams {
+    /** Passed to `importKey` / `generateKey`. */
+    readonly keyParams: EcKeyImportParams | Algorithm;
+    /** Passed to `sign` / `verify`. */
+    readonly signParams: EcdsaParams | Algorithm;
+    /** JWK `kty` the key material must declare. */
+    readonly kty: 'OKP' | 'EC';
+    /** JWK `crv` the key material must declare. */
+    readonly crv: string;
+}
+export declare function algorithmParams(alg: string): AlgorithmParams;
+export declare function isKnownAlgorithm(alg: string): alg is UWSignatureAlgorithm;
+/**
+ * The runtime's Web Crypto implementation.
+ *
+ * Node exposes it as a global from 18.0; Ed25519 specifically landed in 18.4.
+ * An older runtime fails here with a code rather than a `TypeError` on
+ * `undefined.subtle`.
+ */
+export declare function subtle(): SubtleCrypto;

package/dist/algorithms.js

@@ -0,0 +1,55 @@
+// Algorithm parameters for the three algorithms protocol §V.11 admits.
+//
+// The shortlist is borrowed from PASETO v4 and JOSE: one EdDSA curve and two
+// NIST P-curves, all three present in stable Web Crypto. Deliberately no RSA —
+// a 256-byte signature inline in a `_meta` block is a size the format should
+// not have to carry, and nothing in CRE needs it.
+//
+// ECDSA here is the JOSE convention: raw `r || s` (IEEE P1363), which is what
+// Web Crypto produces and consumes. DER-wrapped ECDSA signatures are NOT
+// interchangeable and will fail verification rather than silently pass.
+import { SigningError } from './errors.js';
+const PARAMS = {
+    ed25519: {
+        keyParams: { name: 'Ed25519' },
+        signParams: { name: 'Ed25519' },
+        kty: 'OKP',
+        crv: 'Ed25519',
+    },
+    es256: {
+        keyParams: { name: 'ECDSA', namedCurve: 'P-256' },
+        signParams: { name: 'ECDSA', hash: 'SHA-256' },
+        kty: 'EC',
+        crv: 'P-256',
+    },
+    es384: {
+        keyParams: { name: 'ECDSA', namedCurve: 'P-384' },
+        signParams: { name: 'ECDSA', hash: 'SHA-384' },
+        kty: 'EC',
+        crv: 'P-384',
+    },
+};
+export function algorithmParams(alg) {
+    const params = PARAMS[alg];
+    if (!params) {
+        throw new SigningError('SIG_ALGORITHM_UNSUPPORTED', `Unknown signature algorithm '${alg}'. Protocol 1.x admits ed25519, es256, es384.`);
+    }
+    return params;
+}
+export function isKnownAlgorithm(alg) {
+    return alg in PARAMS;
+}
+/**
+ * The runtime's Web Crypto implementation.
+ *
+ * Node exposes it as a global from 18.0; Ed25519 specifically landed in 18.4.
+ * An older runtime fails here with a code rather than a `TypeError` on
+ * `undefined.subtle`.
+ */
+export function subtle() {
+    const provider = globalThis.crypto?.subtle;
+    if (!provider) {
+        throw new SigningError('SIG_NO_CRYPTO', 'No Web Crypto provider (globalThis.crypto.subtle) in this runtime; @uwmd/signing needs Node >= 18.4 or a browser.');
+    }
+    return provider;
+}

package/dist/base64.d.ts

@@ -0,0 +1,9 @@
+export declare function toBase64Url(bytes: Uint8Array): string;
+export declare function fromBase64Url(text: string): Uint8Array;
+/**
+ * Decode either base64 or base64url. Key material arrives from openssl (base64,
+ * padded) far more often than from a JS encoder, and refusing the common form
+ * on a purely cosmetic difference would be a bad trade for zero safety.
+ */
+export declare function fromBase64Any(text: string): Uint8Array;
+export declare function utf8(text: string): Uint8Array;

package/dist/base64.js

@@ -0,0 +1,60 @@
+// Base64url (RFC 4648 §5, unpadded) and base64 helpers.
+//
+// Hand-rolled rather than reaching for Node's Buffer: this package is
+// browser-usable, and `_meta.signature.sig` must round-trip identically on both
+// sides or every signature written by a browser fails in Node.
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+const B64 = `${ALPHABET}+/`;
+const B64URL = `${ALPHABET}-_`;
+function encodeWith(bytes, alphabet, pad) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes[i];
+        const b1 = bytes[i + 1];
+        const b2 = bytes[i + 2];
+        const triple = (b0 << 16) | ((b1 ?? 0) << 8) | (b2 ?? 0);
+        out += alphabet[(triple >> 18) & 63];
+        out += alphabet[(triple >> 12) & 63];
+        out += b1 === undefined ? (pad ? '=' : '') : alphabet[(triple >> 6) & 63];
+        out += b2 === undefined ? (pad ? '=' : '') : alphabet[triple & 63];
+    }
+    return out;
+}
+function decodeWith(text, alphabet) {
+    const clean = text.replace(/=+$/, '');
+    const bytes = [];
+    let acc = 0;
+    let bits = 0;
+    for (const ch of clean) {
+        const value = alphabet.indexOf(ch);
+        if (value < 0)
+            throw new Error(`invalid base64 character '${ch}'`);
+        acc = (acc << 6) | value;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            bytes.push((acc >> bits) & 0xff);
+        }
+    }
+    return Uint8Array.from(bytes);
+}
+export function toBase64Url(bytes) {
+    return encodeWith(bytes, B64URL, false);
+}
+export function fromBase64Url(text) {
+    return decodeWith(text, B64URL);
+}
+/**
+ * Decode either base64 or base64url. Key material arrives from openssl (base64,
+ * padded) far more often than from a JS encoder, and refusing the common form
+ * on a purely cosmetic difference would be a bad trade for zero safety.
+ */
+export function fromBase64Any(text) {
+    const normalized = text.trim().replace(/\s+/g, '');
+    return /[-_]/.test(normalized)
+        ? decodeWith(normalized, B64URL)
+        : decodeWith(normalized, B64);
+}
+export function utf8(text) {
+    return new TextEncoder().encode(text);
+}

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+export type SigningErrorCode = 
+/** No Web Crypto provider (`crypto.subtle`) in this runtime. */
+'SIG_NO_CRYPTO'
+/** The runtime rejected the algorithm — e.g. Ed25519 on a pre-18.4 Node. */
+ | 'SIG_ALGORITHM_UNSUPPORTED'
+/** Key material could not be imported (wrong format, wrong curve, corrupt). */
+ | 'SIG_BAD_KEY'
+/** The block cannot produce a signing input — almost always a missing hash. */
+ | 'SIG_UNSIGNABLE'
+/** A key-store document is malformed. */
+ | 'SIG_BAD_KEYSTORE';
+export declare class SigningError extends Error {
+    readonly code: SigningErrorCode;
+    constructor(code: SigningErrorCode, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,14 @@
+// Typed errors for the signing package.
+//
+// Mirrors the repo convention (`ProtocolError`, `CalcError`, `ExcelEmitError`):
+// a bare `Error` from a crypto path is unactionable, because the four things
+// that go wrong here — no provider, unusable key material, an unsignable block,
+// an unreadable key store — call for four different fixes.
+export class SigningError extends Error {
+    code;
+    constructor(code, message) {
+        super(`[${code}] ${message}`);
+        this.name = 'SigningError';
+        this.code = code;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { SigningError } from './errors.js';
+export type { SigningErrorCode } from './errors.js';
+export { toBase64Url, fromBase64Url, fromBase64Any } from './base64.js';
+export { isKnownAlgorithm } from './algorithms.js';
+export { InMemoryKeyStore, importPublicKey, importPrivateKey, generateSigningKeyPair, exportPublicKeyJwk, } from './keys.js';
+export type { KeyStore, SignerKey, SigningKey, PublicKeyMaterial } from './keys.js';
+export { loadKeyStoreDocument, parseKeyStore, loadKeyStoreFile, } from './keystore-file.js';
+export type { KeyStoreDocument, KeyStoreEntry } from './keystore-file.js';
+export { signBlock, stampBlockSignature, signReceipt, stampReceiptSignature } from './sign.js';
+export type { SignBlockOptions } from './sign.js';
+export { verifyBlockSignature, createBlockSignatureVerifier, createReceiptSignatureVerifier, } from './verify.js';
+export type { BlockVerification, SigVerifyError } from './verify.js';
+export { signModule, stampModuleSignature, createModuleSignatureVerifier } from './modules.js';
+export type { SignModuleOptions } from './modules.js';
+export declare const SIGNING_PACKAGE_NAME: "@uwmd/signing";
+export declare const SIGNING_VERSION = "0.1.0";

package/dist/index.js

@@ -0,0 +1,23 @@
+// @uwmd/signing — block and receipt signatures for UW Markdown (RFC 0010).
+//
+// Why this is a separate package: `@uwmd/core` is deliberately
+// zero-cryptography. Signed blocks are for regulated lender data rooms and
+// multi-party deal flow, not the everyday case, and the overwhelming majority
+// of adopters should never take a crypto dependency to read an underwriting
+// file. Core defines the wire shape and the canonical signing input (both
+// normative, both crypto-free); the algorithms live here.
+//
+// Two seams connect them, and neither is a back door: `verifyChain(parsed,
+// { signatureVerifier })` for blocks, and `verifyReceipt(..., {
+// signatureVerifier })` for receipts. Without a verifier, core reports that
+// signatures were *present and unchecked* rather than treating them as valid.
+export { SigningError } from './errors.js';
+export { toBase64Url, fromBase64Url, fromBase64Any } from './base64.js';
+export { isKnownAlgorithm } from './algorithms.js';
+export { InMemoryKeyStore, importPublicKey, importPrivateKey, generateSigningKeyPair, exportPublicKeyJwk, } from './keys.js';
+export { loadKeyStoreDocument, parseKeyStore, loadKeyStoreFile, } from './keystore-file.js';
+export { signBlock, stampBlockSignature, signReceipt, stampReceiptSignature } from './sign.js';
+export { verifyBlockSignature, createBlockSignatureVerifier, createReceiptSignatureVerifier, } from './verify.js';
+export { signModule, stampModuleSignature, createModuleSignatureVerifier } from './modules.js';
+export const SIGNING_PACKAGE_NAME = '@uwmd/signing';
+export const SIGNING_VERSION = '0.1.0';

package/dist/keys.d.ts

@@ -0,0 +1,67 @@
+import type { UWSignatureAlgorithm } from '@uwmd/core';
+/** A public key a verifier trusts, resolved from a `kid`. */
+export interface SignerKey {
+    kid: string;
+    alg: UWSignatureAlgorithm;
+    publicKey: CryptoKey;
+}
+/** A private key a signer holds. Never serialized by this package. */
+export interface SigningKey {
+    kid: string;
+    alg: UWSignatureAlgorithm;
+    privateKey: CryptoKey;
+}
+/**
+ * Resolves a `kid` to the public key a verifier should check against.
+ *
+ * `null` means "I do not hold this key" and MUST NOT be conflated with "the
+ * signature is bad" — they are INT-06 and INT-07 respectively, and a verifier
+ * that merges them tells an operator to re-sign when the real fix is to load a
+ * key.
+ */
+export interface KeyStore {
+    resolve(kid: string): Promise<SignerKey | null>;
+}
+/** Key material as it appears in a key-store document. */
+export type PublicKeyMaterial = 
+/** JWK — the portable form; `kty`/`crv` are checked against `alg`. */
+{
+    jwk: JsonWebKey;
+}
+/** PKIX SubjectPublicKeyInfo, base64 or base64url, with or without padding. */
+ | {
+    spki: string;
+};
+export declare function importPublicKey(alg: string, material: PublicKeyMaterial): Promise<CryptoKey>;
+export declare function importPrivateKey(alg: string, material: {
+    jwk: JsonWebKey;
+} | {
+    pkcs8: string;
+}): Promise<CryptoKey>;
+/** An in-memory {@link KeyStore}. The reference verifier for tests and hosts. */
+export declare class InMemoryKeyStore implements KeyStore {
+    private readonly keys;
+    constructor(keys?: Iterable<SignerKey>);
+    add(key: SignerKey): this;
+    resolve(kid: string): Promise<SignerKey | null>;
+    /**
+     * Key ids currently held. Key *rotation* is "issue under a new kid and keep
+     * the old one loaded" (RFC 0010 §Unresolved questions), so a store routinely
+     * holds several keys for one logical signer and this is how an operator sees
+     * that it does.
+     */
+    get kids(): string[];
+}
+/**
+ * Generate a key pair for one of the admitted algorithms.
+ *
+ * Present for tests, local development, and `uwmd keygen`-style tooling — not a
+ * key-management system. Production keys belong in an HSM or cloud KMS behind a
+ * custom {@link KeyStore}.
+ */
+export declare function generateSigningKeyPair(alg: UWSignatureAlgorithm, kid: string): Promise<{
+    signing: SigningKey;
+    verifying: SignerKey;
+}>;
+/** Export a public key as a JWK, for writing into a key-store document. */
+export declare function exportPublicKeyJwk(key: SignerKey): Promise<JsonWebKey>;

package/dist/keys.js

@@ -0,0 +1,102 @@
+// Key import/export and the key-store contract.
+//
+// Key *distribution* is deliberately out of scope — RFC 0010 §Alternatives
+// rejects inline public keys precisely because a key that travels with the
+// document it authenticates proves nothing. What this file defines is the
+// narrow thing the spec does need: how a `kid` resolves to usable key material.
+import { algorithmParams, isKnownAlgorithm, subtle } from './algorithms.js';
+import { fromBase64Any } from './base64.js';
+import { SigningError } from './errors.js';
+export async function importPublicKey(alg, material) {
+    return importKey(alg, material, 'public');
+}
+export async function importPrivateKey(alg, material) {
+    const normalized = 'jwk' in material ? { jwk: material.jwk } : { spki: material.pkcs8 };
+    return importKey(alg, normalized, 'private');
+}
+async function importKey(alg, material, kind) {
+    if (!isKnownAlgorithm(alg)) {
+        throw new SigningError('SIG_ALGORITHM_UNSUPPORTED', `Unknown signature algorithm '${alg}'.`);
+    }
+    const params = algorithmParams(alg);
+    const usages = kind === 'public' ? ['verify'] : ['sign'];
+    try {
+        if ('jwk' in material) {
+            assertJwkMatchesAlgorithm(alg, material.jwk, params.kty, params.crv);
+            return await subtle().importKey('jwk', material.jwk, params.keyParams, true, usages);
+        }
+        const bytes = fromBase64Any(material.spki);
+        const format = kind === 'public' ? 'spki' : 'pkcs8';
+        return await subtle().importKey(format, bytes, params.keyParams, true, usages);
+    }
+    catch (error) {
+        if (error instanceof SigningError)
+            throw error;
+        throw new SigningError('SIG_BAD_KEY', `Could not import the ${kind} key for '${alg}': ${error.message}`);
+    }
+}
+/**
+ * Reject a JWK whose curve disagrees with the declared `alg` *before* handing
+ * it to Web Crypto.
+ *
+ * Without this, a P-256 key labelled `es384` imports cleanly on some runtimes
+ * and then fails every verification, which reads as "the document was tampered
+ * with" when the truth is "the key store is mislabelled".
+ */
+function assertJwkMatchesAlgorithm(alg, jwk, kty, crv) {
+    if (jwk.kty !== kty || jwk.crv !== crv) {
+        throw new SigningError('SIG_BAD_KEY', `Key declares alg '${alg}' (expects kty=${kty}, crv=${crv}) but the JWK is kty=${String(jwk.kty)}, crv=${String(jwk.crv)}.`);
+    }
+}
+/** An in-memory {@link KeyStore}. The reference verifier for tests and hosts. */
+export class InMemoryKeyStore {
+    keys = new Map();
+    constructor(keys = []) {
+        for (const key of keys)
+            this.add(key);
+    }
+    add(key) {
+        this.keys.set(key.kid, key);
+        return this;
+    }
+    async resolve(kid) {
+        return this.keys.get(kid) ?? null;
+    }
+    /**
+     * Key ids currently held. Key *rotation* is "issue under a new kid and keep
+     * the old one loaded" (RFC 0010 §Unresolved questions), so a store routinely
+     * holds several keys for one logical signer and this is how an operator sees
+     * that it does.
+     */
+    get kids() {
+        return [...this.keys.keys()];
+    }
+}
+/**
+ * Generate a key pair for one of the admitted algorithms.
+ *
+ * Present for tests, local development, and `uwmd keygen`-style tooling — not a
+ * key-management system. Production keys belong in an HSM or cloud KMS behind a
+ * custom {@link KeyStore}.
+ */
+export async function generateSigningKeyPair(alg, kid) {
+    const params = algorithmParams(alg);
+    let pair;
+    try {
+        pair = (await subtle().generateKey(params.keyParams, true, [
+            'sign',
+            'verify',
+        ]));
+    }
+    catch (error) {
+        throw new SigningError('SIG_ALGORITHM_UNSUPPORTED', `This runtime cannot generate '${alg}' keys: ${error.message}`);
+    }
+    return {
+        signing: { kid, alg, privateKey: pair.privateKey },
+        verifying: { kid, alg, publicKey: pair.publicKey },
+    };
+}
+/** Export a public key as a JWK, for writing into a key-store document. */
+export async function exportPublicKeyJwk(key) {
+    return subtle().exportKey('jwk', key.publicKey);
+}

package/dist/keystore-file.d.ts

@@ -0,0 +1,32 @@
+import type { UWSignatureAlgorithm } from '@uwmd/core';
+import { type KeyStore } from './keys.js';
+/** One entry. Exactly one of `public_key_jwk` / `public_key_spki` is required. */
+export interface KeyStoreEntry {
+    kid: string;
+    alg: UWSignatureAlgorithm;
+    public_key_jwk?: JsonWebKey;
+    /** PKIX SubjectPublicKeyInfo, base64 (what `openssl pkey -pubout` emits). */
+    public_key_spki?: string;
+    /** Free-text, for humans reading the file. Never consulted by verification. */
+    description?: string;
+}
+export interface KeyStoreDocument {
+    /** `"1"` today. A reader MUST refuse a version it does not know. */
+    keystore_version: string;
+    keys: KeyStoreEntry[];
+}
+/**
+ * Parse and import a key-store document into an {@link InMemoryKeyStore}.
+ *
+ * Every key is imported eagerly. Deferring import to first use would turn a
+ * typo in the store into a per-block INT-07, which reads as tampering; failing
+ * once, loudly, at load time says what is actually wrong.
+ */
+export declare function loadKeyStoreDocument(document: unknown): Promise<KeyStore>;
+/** Parse a key-store document from JSON text. */
+export declare function parseKeyStore(json: string): Promise<KeyStore>;
+/**
+ * Read a key-store document from disk. Node-only by construction — the import
+ * is dynamic so that bundling this module for a browser does not pull in `fs`.
+ */
+export declare function loadKeyStoreFile(path: string): Promise<KeyStore>;

package/dist/keystore-file.js

@@ -0,0 +1,120 @@
+// The reference key-store document: a JSON file mapping `kid` to a public key.
+//
+// RFC 0010 takes no position on key distribution, so this is explicitly a
+// *reference* format, not a normative one — an adopter backing their store with
+// an HSM implements `KeyStore` directly and never touches this file. It exists
+// so that `uwmd verify --signing --keystore=<path>` has something to read and
+// so the conformance fixtures have a portable way to ship a public key.
+import { isKnownAlgorithm } from './algorithms.js';
+import { SigningError } from './errors.js';
+import { InMemoryKeyStore, importPublicKey } from './keys.js';
+const SUPPORTED_KEYSTORE_VERSIONS = ['1'];
+/**
+ * Parse and import a key-store document into an {@link InMemoryKeyStore}.
+ *
+ * Every key is imported eagerly. Deferring import to first use would turn a
+ * typo in the store into a per-block INT-07, which reads as tampering; failing
+ * once, loudly, at load time says what is actually wrong.
+ */
+export async function loadKeyStoreDocument(document) {
+    const parsed = assertKeyStoreDocument(document);
+    const keys = [];
+    for (const entry of parsed.keys) {
+        const material = entry.public_key_jwk
+            ? { jwk: entry.public_key_jwk }
+            : { spki: entry.public_key_spki };
+        keys.push({
+            kid: entry.kid,
+            alg: entry.alg,
+            publicKey: await importPublicKey(entry.alg, material),
+        });
+    }
+    return new InMemoryKeyStore(keys);
+}
+/** Parse a key-store document from JSON text. */
+export async function parseKeyStore(json) {
+    let document;
+    try {
+        document = JSON.parse(json);
+    }
+    catch (error) {
+        throw new SigningError('SIG_BAD_KEYSTORE', `Key store is not valid JSON: ${error.message}`);
+    }
+    return loadKeyStoreDocument(document);
+}
+/**
+ * Read a key-store document from disk. Node-only by construction — the import
+ * is dynamic so that bundling this module for a browser does not pull in `fs`.
+ */
+export async function loadKeyStoreFile(path) {
+    const { readFileSync } = await import('node:fs');
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new SigningError('SIG_BAD_KEYSTORE', `Could not read key store '${path}': ${error.message}`);
+    }
+    return parseKeyStore(text);
+}
+function assertKeyStoreDocument(value) {
+    const fail = (message) => {
+        throw new SigningError('SIG_BAD_KEYSTORE', message);
+    };
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return fail('Key store must be a JSON object.');
+    }
+    const doc = value;
+    const version = doc['keystore_version'];
+    if (typeof version !== 'string')
+        return fail('keystore_version must be a string.');
+    if (!SUPPORTED_KEYSTORE_VERSIONS.includes(version)) {
+        return fail(`Unsupported keystore_version '${version}'; this reader knows ${SUPPORTED_KEYSTORE_VERSIONS.join(', ')}.`);
+    }
+    const keys = doc['keys'];
+    if (!Array.isArray(keys))
+        return fail('keys must be an array.');
+    const seen = new Set();
+    const entries = [];
+    for (const [index, raw] of keys.entries()) {
+        const at = `keys[${index}]`;
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            return fail(`${at} must be an object.`);
+        }
+        const entry = raw;
+        const kid = entry['kid'];
+        if (typeof kid !== 'string' || kid.length === 0)
+            return fail(`${at}.kid must be a non-empty string.`);
+        // A duplicate kid is refused rather than last-wins: the whole point of a
+        // kid is that it names one key, and silently picking one of two makes
+        // verification depend on file order.
+        if (seen.has(kid))
+            return fail(`${at}.kid '${kid}' is declared more than once.`);
+        seen.add(kid);
+        const alg = entry['alg'];
+        if (typeof alg !== 'string' || !isKnownAlgorithm(alg)) {
+            return fail(`${at}.alg must be one of ed25519, es256, es384.`);
+        }
+        const jwk = entry['public_key_jwk'];
+        const spki = entry['public_key_spki'];
+        const hasJwk = jwk !== undefined;
+        const hasSpki = spki !== undefined;
+        if (hasJwk === hasSpki) {
+            return fail(`${at} must carry exactly one of public_key_jwk or public_key_spki.`);
+        }
+        if (hasJwk && (typeof jwk !== 'object' || jwk === null || Array.isArray(jwk))) {
+            return fail(`${at}.public_key_jwk must be an object.`);
+        }
+        if (hasSpki && typeof spki !== 'string') {
+            return fail(`${at}.public_key_spki must be a base64 string.`);
+        }
+        entries.push({
+            kid,
+            alg,
+            ...(hasJwk ? { public_key_jwk: jwk } : {}),
+            ...(hasSpki ? { public_key_spki: spki } : {}),
+            ...(typeof entry['description'] === 'string' ? { description: entry['description'] } : {}),
+        });
+    }
+    return { keystore_version: version, keys: entries };
+}

package/dist/modules.d.ts

@@ -0,0 +1,29 @@
+import { type ModuleManifest, type ModuleSignature, type ModuleSignatureVerifier } from '@uwmd/core';
+import type { KeyStore, SigningKey } from './keys.js';
+export interface SignModuleOptions {
+    /** ISO 8601 instant to stamp as `signed_at`. Defaults to now. */
+    signedAt?: string;
+    /**
+     * Identity claim to embed. Advisory: a signature proves the key holder
+     * asserted this, never that the assertion is true.
+     */
+    identity?: string;
+}
+/**
+ * Sign a module manifest, returning the detached signature.
+ *
+ * Does not mutate the manifest — use {@link stampModuleSignature}. A manifest
+ * that already carries a `signature` can be re-signed: the payload omits the
+ * field, so the old signature does not perturb the new one.
+ */
+export declare function signModule(manifest: ModuleManifest, key: SigningKey, options?: SignModuleOptions): Promise<ModuleSignature>;
+/** Return a copy of `manifest` carrying `signature`. */
+export declare function stampModuleSignature(manifest: ModuleManifest, signature: ModuleSignature): ModuleManifest;
+/**
+ * A {@link ModuleSignatureVerifier} for `verifyModuleSignature` and the async
+ * module loaders.
+ *
+ * Scheme and shape are core's job — it has already run `checkSignatureShape`
+ * before reaching here — so this checks the cryptography and nothing else.
+ */
+export declare function createModuleSignatureVerifier(store: KeyStore): ModuleSignatureVerifier;

package/dist/modules.js

@@ -0,0 +1,56 @@
+// Module manifest signing and verification (RFC 0002, protocol §X.1).
+//
+// Deliberately thin. A module signature is the same act as a block signature
+// over different bytes, so this file is mostly a change of payload — the key
+// handling, the algorithm table, and the actual `subtle.verify` call are the
+// ones `sign.ts` / `verify.ts` already use. Two verifiers would mean two
+// chances to disagree about what a valid signature is.
+import { MODULE_SIGNATURE_SCHEME, moduleSigningPayload, } from '@uwmd/core';
+import { verifyRawSignature } from './verify.js';
+import { signPayload } from './sign.js';
+/**
+ * Sign a module manifest, returning the detached signature.
+ *
+ * Does not mutate the manifest — use {@link stampModuleSignature}. A manifest
+ * that already carries a `signature` can be re-signed: the payload omits the
+ * field, so the old signature does not perturb the new one.
+ */
+export async function signModule(manifest, key, options = {}) {
+    const signedAt = options.signedAt ?? new Date().toISOString();
+    return {
+        scheme: MODULE_SIGNATURE_SCHEME,
+        alg: key.alg,
+        kid: key.kid,
+        sig: await signPayload(moduleSigningPayload(manifest), key),
+        signed_at: signedAt,
+        ...(options.identity !== undefined ? { identity: options.identity } : {}),
+    };
+}
+/** Return a copy of `manifest` carrying `signature`. */
+export function stampModuleSignature(manifest, signature) {
+    return { ...manifest, signature };
+}
+/**
+ * A {@link ModuleSignatureVerifier} for `verifyModuleSignature` and the async
+ * module loaders.
+ *
+ * Scheme and shape are core's job — it has already run `checkSignatureShape`
+ * before reaching here — so this checks the cryptography and nothing else.
+ */
+export function createModuleSignatureVerifier(store) {
+    return {
+        async verify(payload, signature) {
+            const verdict = await verifyRawSignature(payload, signature.alg, signature.kid, signature.sig, store);
+            if (verdict.ok)
+                return { ok: true };
+            // `algorithm_mismatch` folds into `bad_signature` at this seam: core's
+            // ModuleSignatureVerifier contract has three outcomes, and a key whose
+            // curve disagrees with the manifest's claim is a signature that does not
+            // verify, not a shape problem core could have caught.
+            return {
+                ok: false,
+                reason: verdict.reason === 'unknown_kid' ? 'unknown_kid' : verdict.reason === 'malformed' ? 'malformed' : 'bad_signature',
+            };
+        },
+    };
+}

package/dist/sign.d.ts

@@ -0,0 +1,46 @@
+import { type UWBlock, type UWBlockSignature, type UWReceipt, type UWReceiptSignature } from '@uwmd/core';
+import type { SigningKey } from './keys.js';
+export interface SignBlockOptions {
+    /**
+     * ISO 8601 instant to stamp as `signed_at`. Defaults to now.
+     *
+     * Injectable because a signature is only reproducible if its inputs are, and
+     * `signed_at` is one of them — conformance fixtures pin it.
+     */
+    signedAt?: string;
+    /**
+     * Stamp `content_hash` from the block's current content when it is absent.
+     *
+     * Off by default, and deliberately so: signing a block whose hash you just
+     * computed yourself is a different act from signing a hash somebody else
+     * committed to, and quietly doing the former would let a caller sign content
+     * that never passed `verifyChain`.
+     */
+    stampContentHash?: boolean;
+}
+/**
+ * Sign a block, returning the detached {@link UWBlockSignature}.
+ *
+ * The block is not mutated — use {@link stampBlockSignature} to attach the
+ * result. Splitting them keeps the byte-preservation invariant honest: the
+ * caller decides when the document changes.
+ */
+export declare function signBlock(block: UWBlock, key: SigningKey, options?: SignBlockOptions): Promise<UWBlockSignature>;
+/**
+ * Return a copy of `block` carrying `signature` (and, when `signBlock` computed
+ * one, the `content_hash` it committed to).
+ */
+export declare function stampBlockSignature(block: UWBlock, signature: UWBlockSignature, contentHash?: string): UWBlock;
+/**
+ * Sign a verification receipt (RFC 0016). The payload is the receipt with
+ * `signature: null`, canonicalized — `receiptSigningPayload` in core is the
+ * single definition of that, and this package never restates it.
+ */
+export declare function signReceipt(receipt: UWReceipt, key: SigningKey): Promise<UWReceiptSignature>;
+/** Attach a receipt signature, returning a new receipt. */
+export declare function stampReceiptSignature(receipt: UWReceipt, signature: UWReceiptSignature): UWReceipt;
+/**
+ * Sign arbitrary canonical bytes. Shared by blocks, receipts, and module
+ * manifests — the three artifacts differ only in what they canonicalize.
+ */
+export declare function signPayload(payload: string, key: SigningKey): Promise<string>;

package/dist/sign.js

@@ -0,0 +1,81 @@
+// Signing: produce a detached signature over a block or a receipt.
+import { canonicalBlockSigningInput, computeBlockHash, receiptSigningPayload, } from '@uwmd/core';
+import { algorithmParams, subtle } from './algorithms.js';
+import { toBase64Url, utf8 } from './base64.js';
+import { SigningError } from './errors.js';
+/**
+ * Sign a block, returning the detached {@link UWBlockSignature}.
+ *
+ * The block is not mutated — use {@link stampBlockSignature} to attach the
+ * result. Splitting them keeps the byte-preservation invariant honest: the
+ * caller decides when the document changes.
+ */
+export async function signBlock(block, key, options = {}) {
+    let contentHash = block.meta.content_hash;
+    if (typeof contentHash !== 'string' || contentHash.length === 0) {
+        if (!options.stampContentHash) {
+            throw new SigningError('SIG_UNSIGNABLE', `Block '${block.meta.section}' has no _meta.content_hash. Stamp one first (or pass stampContentHash) — a signature over an absent hash commits to nothing and validates as INT-05.`);
+        }
+        contentHash = await computeBlockHash(block);
+    }
+    const signedAt = options.signedAt ?? new Date().toISOString();
+    const payload = canonicalBlockSigningInput({
+        content_hash: contentHash,
+        section: block.meta.section,
+        actor: block.meta.actor,
+        timestamp: block.meta.timestamp,
+        kid: key.kid,
+        signed_at: signedAt,
+    });
+    return {
+        alg: key.alg,
+        kid: key.kid,
+        sig: await signPayload(payload, key),
+        signed_at: signedAt,
+    };
+}
+/**
+ * Return a copy of `block` carrying `signature` (and, when `signBlock` computed
+ * one, the `content_hash` it committed to).
+ */
+export function stampBlockSignature(block, signature, contentHash) {
+    return {
+        ...block,
+        meta: {
+            ...block.meta,
+            ...(contentHash ? { content_hash: contentHash } : {}),
+            signature,
+        },
+    };
+}
+/**
+ * Sign a verification receipt (RFC 0016). The payload is the receipt with
+ * `signature: null`, canonicalized — `receiptSigningPayload` in core is the
+ * single definition of that, and this package never restates it.
+ */
+export async function signReceipt(receipt, key) {
+    return {
+        algorithm: key.alg,
+        key_id: key.kid,
+        value: await signPayload(receiptSigningPayload(receipt), key),
+    };
+}
+/** Attach a receipt signature, returning a new receipt. */
+export function stampReceiptSignature(receipt, signature) {
+    return { ...receipt, signature };
+}
+/**
+ * Sign arbitrary canonical bytes. Shared by blocks, receipts, and module
+ * manifests — the three artifacts differ only in what they canonicalize.
+ */
+export async function signPayload(payload, key) {
+    const params = algorithmParams(key.alg);
+    let bytes;
+    try {
+        bytes = await subtle().sign(params.signParams, key.privateKey, utf8(payload));
+    }
+    catch (error) {
+        throw new SigningError('SIG_BAD_KEY', `Signing with key '${key.kid}' (${key.alg}) failed: ${error.message}`);
+    }
+    return toBase64Url(new Uint8Array(bytes));
+}

package/dist/test-helpers.d.ts

@@ -0,0 +1,4 @@
+import { type ParsedUWFile, type UWBlock } from '@uwmd/core';
+export declare function makeBlock(sectionId: string, content: Record<string, unknown>, meta?: Partial<UWBlock['meta']>): UWBlock;
+export declare function hashedBlock(sectionId: string, content: Record<string, unknown>, meta?: Partial<UWBlock['meta']>): Promise<UWBlock>;
+export declare function makeFile(sections: Record<string, UWBlock>, superseded?: Record<string, UWBlock[]>): ParsedUWFile;

package/dist/test-helpers.js

@@ -0,0 +1,49 @@
+// Block/file fixtures shared by this package's tests.
+//
+// Not exported from `index.ts`: these are test scaffolding, and shipping a
+// block factory in the public API would invite production code to build blocks
+// that never went through the parser.
+import { computeBlockHash } from '@uwmd/core';
+export function makeBlock(sectionId, content, meta = {}) {
+    return {
+        annotation: { section: sectionId },
+        content,
+        meta: {
+            section: sectionId,
+            version: 1,
+            superseded: false,
+            source: 'manual',
+            agent_id: null,
+            agent_version: null,
+            actor: 'human/jared',
+            timestamp: '2026-08-27T00:00:00Z',
+            confidence: 'medium',
+            human_review_required: false,
+            flags: [],
+            input_hash: null,
+            notes: null,
+            ...meta,
+        },
+        prose: '',
+        rawJson: '',
+        lineStart: 1,
+        lineEnd: 1,
+    };
+}
+export async function hashedBlock(sectionId, content, meta = {}) {
+    const block = makeBlock(sectionId, content, meta);
+    return { ...block, meta: { ...block.meta, content_hash: await computeBlockHash(block) } };
+}
+export function makeFile(sections, superseded = {}) {
+    return {
+        frontmatter: { asset_class: 'multifamily' },
+        sections,
+        prose: {},
+        pipeline_log: [],
+        custom_calculations: [],
+        custom_scenarios: [],
+        extensions: {},
+        superseded,
+        raw: '',
+    };
+}

package/dist/verify.d.ts

@@ -0,0 +1,45 @@
+import { type BlockSigFailure, type BlockSignatureVerifier, type BlockSigVerdict, type ReceiptSignatureVerifier, type UWBlock } from '@uwmd/core';
+import type { KeyStore } from './keys.js';
+/** RFC 0010's `SigVerifyError`, plus the hash check core cannot do alone. */
+export type SigVerifyError = BlockSigFailure | 'content_hash_mismatch';
+export type BlockVerification = {
+    ok: true;
+    kid: string;
+} | {
+    ok: false;
+    reason: SigVerifyError;
+    kid?: string;
+};
+/**
+ * Verify a block's signature end to end: recompute the block's `content_hash`,
+ * then check the signature over the canonical signing input.
+ *
+ * The hash recomputation is the part that makes this meaningful. The signature
+ * only commits to a hash *value*; without re-deriving that value from the block
+ * in front of you, a tampered block with its original signature and original
+ * stamped hash verifies happily.
+ */
+export declare function verifyBlockSignature(block: UWBlock, store: KeyStore): Promise<BlockVerification>;
+/**
+ * A {@link BlockSignatureVerifier} for `verifyChain(parsed, { signatureVerifier })`.
+ *
+ * Scoped narrower than {@link verifyBlockSignature} on purpose: `verifyChain`
+ * already recomputes every `content_hash` and reports a mismatch as INT-04, so
+ * repeating that here would report one tampered block twice under two codes.
+ */
+export declare function createBlockSignatureVerifier(store: KeyStore): BlockSignatureVerifier;
+/**
+ * A {@link ReceiptSignatureVerifier} for `verifyReceipt(..., { signatureVerifier })`.
+ *
+ * Without one, a signed receipt verifies as `unverifiable` with RCP-08 — the
+ * one advertised receipt feature that shipped unimplemented until this package
+ * existed.
+ */
+export declare function createReceiptSignatureVerifier(store: KeyStore): ReceiptSignatureVerifier;
+/**
+ * The one place a signature is actually checked. Blocks and receipts carry the
+ * same three facts under different key names (`alg`/`kid`/`sig` vs
+ * `algorithm`/`key_id`/`value`); flattening them here is what keeps the two
+ * surfaces from growing two subtly different verifiers.
+ */
+export declare function verifyRawSignature(payload: string, alg: string, kid: string, sig: string, store: KeyStore): Promise<BlockSigVerdict>;

package/dist/verify.js

@@ -0,0 +1,106 @@
+// Verification: check a detached signature against a key store.
+import { blockSigningPayload, computeBlockHash, } from '@uwmd/core';
+import { algorithmParams, isKnownAlgorithm, subtle } from './algorithms.js';
+import { fromBase64Url, utf8 } from './base64.js';
+/**
+ * Verify a block's signature end to end: recompute the block's `content_hash`,
+ * then check the signature over the canonical signing input.
+ *
+ * The hash recomputation is the part that makes this meaningful. The signature
+ * only commits to a hash *value*; without re-deriving that value from the block
+ * in front of you, a tampered block with its original signature and original
+ * stamped hash verifies happily.
+ */
+export async function verifyBlockSignature(block, store) {
+    const signature = block.meta.signature;
+    if (!signature)
+        return { ok: false, reason: 'malformed' };
+    if (!isWellFormed(signature))
+        return { ok: false, reason: 'malformed', kid: signature.kid };
+    const payload = blockSigningPayload(block);
+    if (payload === null)
+        return { ok: false, reason: 'malformed', kid: signature.kid };
+    const recomputed = await computeBlockHash(block);
+    if (recomputed !== block.meta.content_hash) {
+        return { ok: false, reason: 'content_hash_mismatch', kid: signature.kid };
+    }
+    const verdict = await verifyDetached(payload, signature, store);
+    return verdict.ok ? { ok: true, kid: signature.kid } : { ...verdict, kid: signature.kid };
+}
+/**
+ * A {@link BlockSignatureVerifier} for `verifyChain(parsed, { signatureVerifier })`.
+ *
+ * Scoped narrower than {@link verifyBlockSignature} on purpose: `verifyChain`
+ * already recomputes every `content_hash` and reports a mismatch as INT-04, so
+ * repeating that here would report one tampered block twice under two codes.
+ */
+export function createBlockSignatureVerifier(store) {
+    return {
+        async verify(payload, signature) {
+            if (!isWellFormed(signature))
+                return { ok: false, reason: 'malformed' };
+            return verifyDetached(payload, signature, store);
+        },
+    };
+}
+/**
+ * A {@link ReceiptSignatureVerifier} for `verifyReceipt(..., { signatureVerifier })`.
+ *
+ * Without one, a signed receipt verifies as `unverifiable` with RCP-08 — the
+ * one advertised receipt feature that shipped unimplemented until this package
+ * existed.
+ */
+export function createReceiptSignatureVerifier(store) {
+    return {
+        async verify(receipt, signedPayload) {
+            const signature = receipt.signature;
+            if (!signature)
+                return false;
+            const verdict = await verifyRawSignature(signedPayload, signature.algorithm, signature.key_id, signature.value, store);
+            return verdict.ok;
+        },
+    };
+}
+function verifyDetached(payload, signature, store) {
+    return verifyRawSignature(payload, signature.alg, signature.kid, signature.sig, store);
+}
+/**
+ * The one place a signature is actually checked. Blocks and receipts carry the
+ * same three facts under different key names (`alg`/`kid`/`sig` vs
+ * `algorithm`/`key_id`/`value`); flattening them here is what keeps the two
+ * surfaces from growing two subtly different verifiers.
+ */
+export async function verifyRawSignature(payload, alg, kid, sig, store) {
+    if (!isKnownAlgorithm(alg))
+        return { ok: false, reason: 'algorithm_mismatch' };
+    const key = await store.resolve(kid);
+    if (!key)
+        return { ok: false, reason: 'unknown_kid' };
+    if (key.alg !== alg)
+        return { ok: false, reason: 'algorithm_mismatch' };
+    let sigBytes;
+    try {
+        sigBytes = fromBase64Url(sig);
+    }
+    catch {
+        return { ok: false, reason: 'malformed' };
+    }
+    const params = algorithmParams(alg);
+    let ok;
+    try {
+        ok = await subtle().verify(params.signParams, key.publicKey, sigBytes, utf8(payload));
+    }
+    catch {
+        // Web Crypto throws on a signature of the wrong length for the curve
+        // rather than returning false. That is malformed input, not a bad key.
+        return { ok: false, reason: 'malformed' };
+    }
+    return ok ? { ok: true } : { ok: false, reason: 'bad_signature' };
+}
+function isWellFormed(signature) {
+    return (typeof signature.alg === 'string' &&
+        typeof signature.kid === 'string' &&
+        signature.kid.length > 0 &&
+        typeof signature.sig === 'string' &&
+        signature.sig.length > 0);
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@uwmd/signing",
+  "version": "0.1.0",
+  "description": "Block and receipt signing for UW Markdown (RFC 0010) — Ed25519 / ES256 / ES384 over the normative signing inputs, with a file-backed reference key store. Kept out of @uwmd/core so the library stays crypto-free.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/UWMD-OSP/UW-Markdown.git",
+    "directory": "packages/uwmd-signing"
+  },
+  "homepage": "https://uwmd.org",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
+    "./keystore-file": { "import": "./dist/keystore-file.js", "types": "./dist/keystore-file.d.ts" }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck:tests": "tsc -p tsconfig.test.json"
+  },
+  "dependencies": { "@uwmd/core": "1.8.0" },
+  "devDependencies": { "@types/node": "^20.0.0", "typescript": "^5.4.0", "vitest": "^3.2.6" },
+  "engines": { "node": ">=18.4.0" },
+  "license": "MIT",
+  "keywords": [
+    "uwmd",
+    "underwriting",
+    "commercial-real-estate",
+    "signing",
+    "ed25519",
+    "provenance"
+  ]
+}