@charter-agreement-protocol/signer 0.2.1 → 0.3.0

package/README.md

@@ -7,15 +7,12 @@ Holder-side companion signer for the
 
 **CAP verifies; it never authorizes. This signer signs; it never takes
 custody.** You keep the key (HSM, OS keychain, key server) behind a handle
-object with two callbacks; the signer resolves ONE atomic `keyIdentity`
-snapshot, then delegates EVERYTHING pure to the verifier package's producer
-surface — the exact RFC 7515 signing input, the producer claims gate, the
-R1–R3 honest-signer refusal guards (claims-truth, no-equivocation,
-ancestry/governing coverage), and assembly — **before the key signs**, with
-exactly one implementation. What stays here is custody: the sign callback,
-the wrong-key guard against the snapshot's public key, and the post-sign
-verification of the assembled artifact through the
-`@charter-agreement-protocol/verifier` package.
+with two callbacks. The signer resolves limits, profile, and algorithm, copies
+claims and context at entry, and takes one atomic `keyIdentity` snapshot.
+The verifier's `prepareSigning` checks framing, claims, context, profile,
+limits, and the holder's own descriptor key before the callback signs.
+The signer checks the signature against the snapshot public key, then calls
+`finishSigning` to assemble and verify under the retained context and settings.
 
 ## Install
 
@@ -23,13 +20,18 @@ verification of the assembled artifact through the
 npm install @charter-agreement-protocol/signer
 ```
 
-Requires Node >= 24.8 (ML-DSA support in the Node builtins).
+Version **0.3.0** requires Node >= 24.8.0 and
+`@charter-agreement-protocol/verifier` ^0.7.0, for its pre-sign API.
 
 ## Quickstart
 
+This runnable Ed25519 example keeps the private key in a Node `KeyObject`.
+For an HSM, OS keychain, or remote key server, replace the handle's callbacks
+with your custodian's key identity and signing operations.
+
 ```js
 import { signDescriptor } from "@charter-agreement-protocol/signer";
-import { generateKeyPairSync } from "node:crypto";
+import { generateKeyPairSync, sign as nodeSign } from "node:crypto";
 
 const { publicKey, privateKey } = generateKeyPairSync("ed25519");
 const publicKeyBase64url = publicKey.export({ type: "spki", format: "der" }).subarray(-32).toString("base64url");
@@ -41,7 +43,7 @@ const handle = {
   },
   // The holder's job: sign the exact message bytes with the held key.
   sign(message) {
-    return myHsm.sign(message); // Uint8Array signature
+    return nodeSign(null, message, privateKey); // Buffer is a Uint8Array
   },
 };
 
@@ -54,86 +56,188 @@ const result = await signDescriptor(
     ],
     attestation_hints: [],
     extensions: { critical: {}, optional: {} },
-    effective_from: "2026-08-25T10:00:00Z",
+    effective_from: new Date().toISOString(),
   },
   handle,
 );
 
-// result.ok === true: { descriptor } is a CAP-verified compact JWS.
+if (!result.ok) throw new Error(JSON.stringify(result));
+console.log(result.result.descriptor); // Post-verified compact JWS
 ```
 
 For ML-DSA-65 artifacts pass `{ algorithm: "ML-DSA-65" }` as the options
 argument with `protocol_revision: 3` claims (pure ML-DSA per RFC 9964, the
 empty context — your handle signs the exact message bytes as with Ed25519).
 
+An absent, `undefined` or `null` algorithm selects Ed25519. Explicit
+algorithms are `Ed25519` and `ML-DSA-65`; any other value returns
+`invalid_input` with `code: "algorithm_unsupported"` before either key
+callback runs.
+
 ## API
 
 | Export | What it does |
 |---|---|
-| `signDescriptor(claims, handle, opts?)` | Signs one Party Descriptor; post-verified via `verifyDescriptor` |
-| `signReceipt(claims, handle, chain, opts?)` | Signs one Receipt against the required issuing view; post-verified via `verifyReceipt` (the reference takes a context, never none) |
-| `signAcceptance(claims, handle, view, opts?)` | Signs one Acceptance against the caller's verified view — the R1–R3 refusal guards run over `view.chain` before the key signs |
-| `signTermination(claims, handle, view, opts?)` | Signs one Termination against the caller's verified view — the R1–R3 refusal guards run over `view.chain` before the key signs |
-
-The acceptance/termination `view` is `{ revisionText, descriptorCompacts,
-chain }`: the revision the claims name, the signing party's descriptor
-chain, and the caller's full `ChainView` (`{ revisions, acceptances,
-descriptors, terminations }`) the refusal guards verify and bind against.
-
-Errors are closed: `{ ok: false, error: "invalid_handle" \| "signing_failed"
-\| "invalid_input" \| "refused" \| "verification_failed" }` — `code` rides
-only on `invalid_input` and `refused`; `verification_failed` is bare
-(reference parity).
-`"refused"` is the honest-signer refusal: the claims contradict the caller's
-own verified view, and the handle's `sign` callback is never reached (the
-atomic `keyIdentity` snapshot resolves first — the reference ordering).
-`"verification_failed"` is the separate post-sign discipline: the assembled
-artifact did not verify against the caller's view (for example a key that is
-not in the party descriptor's `verification_keys`). Malformed claims are
-rejected pre-sign as `"invalid_input"` through the verifier package's
-producer claims gate — they never burn a key operation. A signing failure is
-never a silent pass.
+| `signDescriptor(claims, handle, opts?)` | Signs a genesis or successor Party Descriptor; successors require `opts.predecessor` |
+| `signReceipt(claims, handle, context, opts?)` | Signs a Receipt against a chain view or bare revision text |
+| `signAcceptance(claims, handle, chain, opts?)` | Signs an Acceptance using the context the verifier derives from the chain |
+| `signTermination(claims, handle, chain, opts?)` | Signs a Termination using the context the verifier derives from the chain |
+| `SigningOptions`, `DescriptorOptions`, `ChainView`, `KeyHandle`, `KeySnapshot`, `SignError`, `SignResult` | Public TypeScript contracts |
 
-## The sibling verifier
+A `ChainView` contains four string arrays: `{ revisions, acceptances,
+descriptors, terminations }`. Pass all four, including explicit empty arrays.
+Acceptance and termination use this chain directly. The verifier derives the
+claimed revision and the holder's own descriptor history from its verified
+contents. The signer copies claims at entry, before awaiting a key callback.
+Claims copies contain fresh plain JSON objects and arrays, strings, finite
+numbers, booleans, and null. Repeated objects are copied separately. Non-JSON
+claims, cycles, and throwing reads return `invalid_input`/`invalid_type`.
+Chain context and predecessor use their defined members with ordinary property
+reads, and retained artifact lists get fresh arrays. Valid members are immutable
+text; invalid member values stay opaque for the verifier.
 
-This package is one of two independent TypeScript siblings implementing the
-Charter Agreement Protocol — no Elixir code or dependency at runtime; the
-Elixir reference is the certification oracle (the verifier's vendored
-corpus is certified against it, and its CI cross-verifies
-TypeScript-signed artifacts from raw bytes).
+Claims copies use an iterative traversal guarded by the verifier's maximum
+supported JSON bounds, rather than the caller's limits. Values beyond those
+maximums return `invalid_input`/`signing_input_invalid`. Smaller claims reach
+`prepareSigning`, which owns all checks under caller limits, including final
+compact size. Context list copies retain enough entries to exceed every
+supported artifact item limit, letting the verifier return its own result.
+Predecessor lineage has no signer item limit. The verifier checks immutable
+artifact text under artifact byte limits, separately from parsed claims' string
+limits.
 
-- **This package** — `@charter-agreement-protocol/signer`: key custody,
-  the wrong-key guard, post-sign verification, and the closed error
-  vocabulary — all protocol logic delegated to the verifier.
-- [`@charter-agreement-protocol/verifier`](https://www.npmjs.com/package/@charter-agreement-protocol/verifier)
-  — verification and the pure producer surface (signing inputs, claims
-  gate, refusal guards, assembly) that this package signs through.
+Migration from the previous issuing view:
+
+```ts
+// Before
+await signAcceptance(claims, handle, { revisionText, descriptorCompacts, chain }, opts);
+// Now
+await signAcceptance(claims, handle, chain, opts);
+await signTermination(terminationClaims, handle, chain, opts);
+```
+
+For a successor descriptor, pass the verifier's `DescriptorPredecessor` facts
+with retained signed `lineage`. The signing key must match an active key in
+the predecessor:
+
+```ts
+import { verifyDescriptor } from "@charter-agreement-protocol/verifier";
+
+const previous = verifyDescriptor(genesisCompact);
+if (!previous.ok) throw new Error(previous.code);
+const next = await signDescriptor(successorClaims, handle, { predecessor: previous.facts });
+```
+
+For a receipt against bare revision text, the verifier checks the receipt's
+claims against that revision. The revision names no signing key, so the signer
+uses its snapshot for the custody guard; receipt verification reports
+`signature` in `not_verified`. A chain-backed receipt checks the key against
+the issuing party's descriptor keys in the holder's own view.
+
+`opts` is absent or an object with known own keys only: `algorithm`, `limits`,
+and `profile`, plus `predecessor` for `signDescriptor`. Another root shape, an
+unknown own key, or a throwing getter returns `invalid_input` with
+`code: "invalid_type"`. Defined members use ordinary property reads, once at
+entry, including inherited and nonenumerable members. Class instances and
+`Map` objects work where the verifier accepts their properties; Map entries
+are not option properties.
+
+`limits` is the verifier's `Partial<Limits>` and `profile` is its `Profile`.
+The signer reads only their defined shape. Invalid values stay opaque for the
+verifier's synchronous checks; they are not recursively copied by the signer.
+Limits are checked before profile, algorithm, and the key snapshot. Malformed
+values, including bigint, symbol, and boxed numbers, retain the verifier's
+`invalid_limits` or `invalid_profile` result. Sparse algorithm lists return
+`invalid_profile`; nonfinite or explicitly undefined limit values return
+`invalid_limits`. A list longer than the algorithm registry cannot be a valid
+unique subset, so its invalid length reaches the verifier without reading its
+entries. The verifier's copy failures are also returned unchanged.
+Limits bound the final compact, including signature bytes, and
+every context artifact read; raised limits also apply to assembly and the
+custody guard. Profiles can restrict `algorithms` and/or
+`revisions: { min, max }`; an omitted axis keeps the full supported range.
+An EdDSA-only profile, an ML-DSA-44/87-only profile, or revisions 1..1 excludes
+every artifact this signer emits. Exclusions return `algorithm_outside_profile`
+or `revision_outside_profile`.
+
+<a id="profile-scope"></a>
+
+For acceptance and termination, the caller's profile covers the claimed
+revision, the signing party's own descriptor history, and the new artifact.
+The rest of the set is checked under the full default profile. For receipts,
+the profile covers the new artifact and the whole retained set. For descriptors,
+it covers the new artifact and predecessor history.
+
+Errors are closed:
+
+| Result error | Meaning |
+|---|---|
+| `invalid_input`, with `code` | The verifier rejected claims, context, limits, or profile, or options were invalid |
+| `invalid_key_handle` | The snapshot callback failed, its shape was malformed, or the verifier returned `signing_key_invalid` |
+| `refused`, with `code: "signing_refused"` | The claims contradict the holder's own verified view (R1–R3) |
+| `refused`, with `code: "signing_key_mismatch"` | The kid, public key bytes, or key algorithm does not match the holder's own descriptor key |
+| `algorithm_unsupported_on_substrate` | The runtime cannot verify the selected algorithm or a context artifact |
+| `signing_failed` | The callback failed, returned a malformed signature, or failed the wrong-key guard |
+| `verification_failed` | `finishSigning` rejected what preparation approved |
 
-The pair releases together: this package depends on the verifier (`^0.4.0`),
-so a verifier release stages first and the signer locks and releases
-against the published version immediately after.
+Every failure has `ok: false`. Only `invalid_input` and `refused` carry `code`.
+The signing callback can return a Buffer or any `Uint8Array`, including one
+from another JavaScript realm. The verifier rejects Ed25519 public keys with
+noncanonical y coordinates, no curve point, x = 0 with the sign bit set, or
+small order as `invalid_key_handle` when they are snapshot keys. Descriptor
+claims containing such keys can fail earlier with `signing_input_invalid`.
+All pre-sign rejections leave the `sign` callback untouched; the atomic key
+snapshot precedes `prepareSigning`. A malformed context type returns
+`invalid_input`/`invalid_type`. For otherwise valid descriptor claims, predecessor
+errors return `invalid_input` with these codes before signing:
+
+- `invalid_type`: a non-object predecessor, a missing digest alias (both `digest`
+  and `descriptor_digest` absent), or missing, null, empty, or non-string `lineage`.
+  Throwing reads also return this code.
+- `descriptor_chain_invalid`: an absent or null predecessor for a successor,
+  a valid predecessor supplied to a genesis, a broken signed lineage, or digest
+  aliases that disagree with the reverified lineage.
+- `algorithm_outside_profile`, `revision_outside_profile`, or
+  `algorithm_unsupported_on_substrate`: predecessor history excluded by the
+  profile or requiring unavailable crypto.
+
+## The sibling verifier
+
+The signer and verifier are separate TypeScript packages implementing the
+Charter Agreement Protocol, with no Elixir dependency at runtime. The
+verifier ships a corpus certified against the Elixir protocol reference.
+This signer tests its artifacts through the TypeScript verifier.
+All protocol checks run in `prepareSigning` and `finishSigning`; the signer
+keeps key custody callbacks, the signature guard, entry copies, option
+resolution, and the closed error vocabulary.
 
 ## Evidence
 
-- The Elixir reference repository's gate verifies TypeScript-signed
-  artifacts from raw bytes (cross-implementation agreement, enforced in CI).
-- Framing, the producer claims gate, refusal guards, and assembly are the
-  verifier package's producer surface (0.4.0) — the same single
-  implementation the independent verifier certifies. What remains here is
-  custody plus input policing: the issuing-view discipline composes the
-  verifier's own `verifyChain`, never a local reimplementation.
-- Post-sign verification goes through the
-  [@charter-agreement-protocol/verifier](https://www.npmjs.com/package/@charter-agreement-protocol/verifier)
-  package — the certified dual-implementation-verified verifier.
-
-## The verify side
-
-This package tracks the published verify line: it depends on
-`@charter-agreement-protocol/verifier` `^0.5.0`. Verifier 0.5.0 added
-consumer-side surface only; the producer surface this package uses is
-unchanged. The producer-side capability alignment (mirrored
-`capabilities()` with refuse-before-mint, declared minting metadata,
-profile-bound signing) is the next feature release on this line.
+- Linux CI runs the suite on Node 24.8.0 and the current Node 24 line.
+  Real Node crypto mints Ed25519 and ML-DSA-65 genesis and successor descriptors.
+  Pre-sign rejection tests count real signing calls and require zero calls.
+  Tests cover key mismatches, predecessor checks, malformed contexts, profiles,
+  final compact limits, receipt claims, entry copies, and unknown algorithms.
+- The workshop's browser bundle mints Ed25519 and runs the complete workshop
+  flow. It cannot verify ML-DSA-65 and refuses that request before signing with
+  the top-level `algorithm_unsupported_on_substrate` error.
+- The [shared table](test/fixtures/README.md) runs all 121 rows from the Elixir
+  signer, `charter_agreement_signer` 0.5.0, with its exact source bytes pinned by SHA-256. Real seed
+  keys check result shapes and codes, snapshot and custody counts, 12 exact
+  Ed25519 success compacts, and five ML-DSA-65 successes through verification.
+  All 121 rows run in both Node and the browser bundle with no skips. Eight
+  shared requests or contexts that need ML-DSA-65 also return a substrate error
+  before custody in the browser bundle.
+  This compares the recorded Elixir outcomes; it does not run Elixir locally.
+
+## Verifier compatibility and telemetry
+
+The verifier requires canonical digests and revision JSON, distinct party
+histories, and all four chain arrays. Build failures surface as `invalid_input`
+with `code: "signing_input_invalid"`; termination claims must omit `extensions`.
+See [CHANGELOG.md](CHANGELOG.md) for migration notes.
+
+This package has no telemetry events or hooks and no signer capability report.
 
 ## SemVer
 
@@ -145,6 +249,42 @@ requires `chain`, `signAcceptance` now enforces the refusal guards over the
 at or above 1.0 a package major is owed when a shipped public API is removed
 or changes behavior.
 
+## Development
+
+Use Node 24 (at least 24.8.0) and npm. The lockfile selects TypeScript 7.0.2
+and `@types/node` 26.6.4. CI runs on Linux with Node 24.8.0 and Node 24
+using a frozen install; the same npm commands are used for local development on macOS and Linux.
+
+```console
+npm ci
+npm run typecheck
+npm test
+npm run test:cases
+npm run build
+npm run typecheck:web
+npm run build:site
+npm pack --dry-run
+```
+
+`build` emits JavaScript and declarations into `dist/`; `build:site` writes
+the browser workshop to `site-dist/`. `prepack` runs the library build.
+For the TypeScript 7 upgrade, the four library output files were byte-identical
+to the TypeScript 5.9.3 build (observed October 6, 2026 with `diff -ru`).
+
+## Release staging
+
+The [Release workflow](https://github.com/baselabs/charter_agreement_signer_typescript/blob/main/.github/workflows/release.yml) is the npm trusted
+publisher for this repository. Prepare a release by updating `package.json`,
+`package-lock.json`, this README's release version, the CHANGELOG, and the
+workshop's version badge. Run the development checks above, commit and push
+main, and wait for CI to pass. Then tag that same commit `v<package-version>`
+and push that specific tag.
+
+The tag triggers verification and `npm stage publish --provenance` through
+GitHub Actions OIDC. A successful staging step prints the package version and
+stage ID. The package becomes public only after the owner approves the staged
+release on npmjs.com with 2FA. Keep npm staging in this workflow.
+
 ## License
 
 Apache-2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/SECURITY.md

@@ -0,0 +1,55 @@
+# Security policy
+
+## Supported versions
+
+The latest published `0.x` line is supported. Wire compatibility follows
+the public `@charter-agreement-protocol/verifier` package's contract.
+
+## Security invariants
+
+- The library never solicits, processes or retains private key material.
+  Custody lives behind the caller's key-handle callbacks.
+- Every signature is verified against the snapshot public key before
+  success. A signature from another key returns `signing_failed`.
+- Key identity (`kid` and public key) comes from one atomic `keyIdentity`
+  snapshot per signing call. The signer supplies that snapshot's kid to
+  the producer.
+- Errors contain closed names and codes, with no key material, message
+  bytes, claims content or callback exception text.
+- The library's only runtime dependency is the public verifier package.
+  It contains no transport or HTTP client/server.
+- Test handles stay in test files and do not ship in the npm package.
+
+## Reporting a vulnerability
+
+Report it privately through GitHub's private vulnerability reporting for
+`baselabs/charter_agreement_signer_typescript` (the repository's Security
+tab, then "Report a vulnerability"). Do not open a public issue containing
+an exploit, credential, private key or unreleased vulnerability detail.
+
+A report should include:
+
+- the affected version or commit;
+- the violated property;
+- a minimal reproduction with newly generated test keys and no production
+  claims or credentials;
+- the expected security outcome.
+
+## Verifying a release
+
+The [Release workflow](https://github.com/baselabs/charter_agreement_signer_typescript/blob/main/.github/workflows/release.yml)
+checks the package before staging it on npm with provenance through
+GitHub Actions OIDC. The owner approves the staged release on npm with 2FA.
+Inspect the published package's source repository, archive integrity and
+provenance metadata with:
+
+```console
+npm view @charter-agreement-protocol/signer repository.url dist.integrity dist.attestations
+```
+
+## Acknowledgment
+
+We will acknowledge reports within 7 days and send status updates at least
+weekly until resolution, coordinating disclosure through a private advisory.
+This is a best-effort cadence from a small maintainer team, not a contractual
+SLA. Mark urgent reports clearly.

package/dist/index.d.ts

@@ -1 +1 @@
-export { signDescriptor, signReceipt, signAcceptance, signTermination, type KeyHandle, type KeySnapshot, type ChainView, type SignError, type SignResult, } from "./signer.ts";
+export { signDescriptor, signReceipt, signAcceptance, signTermination, type KeyHandle, type KeySnapshot, type ChainView, type SigningOptions, type DescriptorOptions, type SignError, type SignResult, } from "./signer.ts";

package/dist/index.js

@@ -2,8 +2,6 @@
 //
 // Public surface of the holder-side companion signer: one signing function
 // per artifact kind, the key-handle contract, and the closed error
-// vocabulary. ALL protocol logic — framing, the producer claims gate, the
-// R1-R3 refusal guards, assembly, and verification of the assembled
-// artifact — goes through @charter-agreement-protocol/verifier: exactly
-// one implementation. This package holds the custody half only.
+// vocabulary. Protocol checks run through prepareSigning and finishSigning
+// in @charter-agreement-protocol/verifier. This package keeps custody.
 export { signDescriptor, signReceipt, signAcceptance, signTermination, } from "./signer.js";

package/dist/signer.d.ts

@@ -1,3 +1,4 @@
+import { type DescriptorPredecessor, type Limits, type Profile } from "@charter-agreement-protocol/verifier";
 export type KeySnapshot = {
     kid: string;
     publicKey: string;
@@ -7,7 +8,7 @@ export type KeyHandle = {
     sign(message: Uint8Array, handle: unknown): Uint8Array | Promise<Uint8Array>;
 };
 export type SignError = {
-    error: "invalid_handle";
+    error: "invalid_key_handle";
 } | {
     error: "signing_failed";
 } | {
@@ -15,7 +16,9 @@ export type SignError = {
     code: string;
 } | {
     error: "refused";
-    code: string;
+    code: "signing_refused" | "signing_key_mismatch";
+} | {
+    error: "algorithm_unsupported_on_substrate";
 } | {
     error: "verification_failed";
 };
@@ -32,31 +35,23 @@ export type ChainView = {
     descriptors: string[];
     terminations: string[];
 };
-export declare function signDescriptor(claims: Record<string, unknown>, keyHandle: unknown, opts?: {
-    algorithm?: string;
-}): Promise<SignResult<{
+export type SigningOptions = {
+    algorithm?: string | null;
+    limits?: Partial<Limits>;
+    profile?: Profile;
+};
+export type DescriptorOptions = SigningOptions & {
+    predecessor?: DescriptorPredecessor | null;
+};
+export declare function signDescriptor(claims: Record<string, unknown>, keyHandle: unknown, opts?: DescriptorOptions): Promise<SignResult<{
     descriptor: string;
 }>>;
-export declare function signReceipt(claims: Record<string, unknown>, keyHandle: unknown, chain: ChainView, opts?: {
-    algorithm?: string;
-}): Promise<SignResult<{
+export declare function signReceipt(claims: Record<string, unknown>, keyHandle: unknown, context: ChainView | string, opts?: SigningOptions): Promise<SignResult<{
     receipt: string;
 }>>;
-export declare function signAcceptance(claims: Record<string, unknown>, keyHandle: unknown, view: {
-    revisionText: string;
-    descriptorCompacts: string[];
-    chain: ChainView;
-}, opts?: {
-    algorithm?: string;
-}): Promise<SignResult<{
+export declare function signAcceptance(claims: Record<string, unknown>, keyHandle: unknown, chain: ChainView, opts?: SigningOptions): Promise<SignResult<{
     acceptance: string;
 }>>;
-export declare function signTermination(claims: Record<string, unknown>, keyHandle: unknown, view: {
-    revisionText: string;
-    descriptorCompacts: string[];
-    chain: ChainView;
-}, opts?: {
-    algorithm?: string;
-}): Promise<SignResult<{
+export declare function signTermination(claims: Record<string, unknown>, keyHandle: unknown, chain: ChainView, opts?: SigningOptions): Promise<SignResult<{
     termination: string;
 }>>;