@bounded-authority-protocol/verifier 0.2.0 → 0.2.2

package/README.md

@@ -125,6 +125,105 @@ local-development proof profile (`localLoopbackHttpProofSigningInput` and friend
 `127.0.0.1`/`[::1]` targets only, mandatory nonce; standard `dpop+jwt` rejects its bytes).
 The full export list is [`src/index.ts`](src/index.ts).
 
+## Pairing with the signer
+
+This package verifies; it never signs and never holds a private key. Its sibling
+[`@bounded-authority-protocol/signer`](https://www.npmjs.com/package/@bounded-authority-protocol/signer)
+produces the signed bytes — and it does so by calling THIS package's producer functions
+(`grantSigningInput`, `proofSigningInput`, `boundaryAnchorSigningInput`,
+`keyTransitionSigningInput`) and delegating the cryptography to a caller-owned key handle.
+The dependency direction is one-way: the signer depends on the verifier at runtime
+(`^0.2.0`), never the reverse. Compatibility between the two is governed by the wire
+contract-majors — both packages carry majors 1 and 2 side by side — not by package
+version numbers.
+
+A production flow has three roles: the issuer mints a grant, the holder binds one
+invocation of it with a proof, and the resource verifies the pair through this package.
+
+```ts
+// Issuer — mint a grant. The private key never enters the signer; your handle
+// routes each sign() to your own custody (KMS, HSM, or an in-process test key).
+import { signGrant, signReport, type KeyHandle } from "@bounded-authority-protocol/signer";
+import { checkEnvelope } from "@bounded-authority-protocol/verifier";
+
+const issuerHandle: KeyHandle = {
+  sign: (message) => issuerCustody.sign(message),  // Ed25519, 64 bytes
+  publicKey: () => issuerPublicKey32,
+  thumbprint: () => issuerThumbprint,              // RFC 7638, base64url
+  // Grants additionally require an atomic issuer-role identity — the C1 gate:
+  // a holder-role handle fails closed before sign() is ever called.
+  signingIdentity: () => ({ role: "issuer", keyId: "issuer-key", publicKey: issuerPublicKey32 }),
+};
+
+// SignerResult mirrors this package's Result<T>: check ok before reading value.
+const grantResult = await signGrant(
+  {
+    issuer: "https://issuer.example",
+    grantId: "g-1",
+    audiences: ["https://resource.example"],
+    issuedAt: 1_731_728_000,
+    notBefore: 1_731_728_000,
+    expiresAt: 1_733_728_000,
+    holderThumbprint,  // RFC 7638 base64url of the holder's public JWK (the thumbprint primitive)
+    operations: [
+      { name: "transfer", selectors: [{ kind: "equals", path: ["amount"], value: { t: "int", v: 5000 } }] },
+    ],
+  },
+  issuerHandle,
+);
+if (!grantResult.ok) throw new Error(`signing failed: ${grantResult.error}`);
+const grantCompact = grantResult.value.grant;
+
+// Holder — bind one invocation of that grant with a holder proof. The holder's
+// handle is constructed exactly like the issuer's (reports need no
+// signingIdentity — proofs are holder-signed by definition), and the proof
+// timestamp is pinned the same way: this verifier reads no clock.
+const proofResult = await signReport(
+  {
+    grantCompact: grantCompact,
+    operation: "transfer",
+    method: "POST",
+    targetUri: "https://api.example.test/invoke",
+    invocationId: "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",  // a lowercase RFC 4122 UUID — the wire requires it
+    castArguments: { t: "object", v: new Map([["amount", { t: "int", v: 5000 }]]) },
+  },
+  holderHandle,
+  { issuedAt: 1_731_728_030 },
+);
+if (!proofResult.ok) throw new Error(`signing failed: ${proofResult.error}`);
+const envelope = proofResult.value;
+
+// Resource — THIS package, and nothing else. Facts, never a decision.
+const result = checkEnvelope(envelope.grant, envelope.proof, {
+  trustedIssuer: { keyId: "issuer-key", publicKey: issuerPublicKey32 },
+  issuer: "https://issuer.example",
+  audience: "https://resource.example",
+  method: "POST",
+  targetUri: "https://api.example.test/invoke",
+  invocationId: "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
+  operation: "transfer",
+  castArguments: { t: "object", v: new Map([["amount", { t: "int", v: 5000 }]]) },
+  evaluationTime: 1_731_728_060,
+  clockSkew: 60,
+  proofMaxAge: 300,
+  nonce: { kind: "not_required" },
+});
+```
+
+Two properties make the pairing safe to build against:
+
+- **Key custody stays at the caller.** The signer's `KeyHandle` is a callback interface
+  (`sign`/`publicKey`/`thumbprint`, plus atomic `keyIdentity`/`signingIdentity` snapshots
+  for anchors, transitions, and role-gated grant signing). A handle fault or a
+  wrong-key rotation race fails loudly as `signing_failed` — the signer verifies every
+  signature against the resolved public key before assembly. The full contract is
+  documented in the [signer's README](https://github.com/baselabs/bounded_authority_signer_typescript#readme).
+- **The two packages cross-validate in CI.** The signer's test oracle produces
+  compacts through its own surface and verifies every one of them through THIS
+  package before release — signing-side drift is caught in the signer's CI against
+  the verifier version its lockfile resolves, and verifier-side changes are gated
+  by this package's certified conformance corpora.
+
 ## Certified, not self-tested
 
 Every release of this SDK is verified against the protocol's published, cryptographically
@@ -167,6 +266,18 @@ the host — a facts value is evidence, never a credential.
 - [ADR 0014 — cross-language verifier SDKs](https://github.com/baselabs/bounded_authority_protocol/blob/main/docs/adr/0014-cross-language-verifier-sdks.md) ·
   [ADR 0015 — graduation and publish topology](https://github.com/baselabs/bounded_authority_protocol/blob/main/docs/adr/0015-sdk-graduation-and-publish-topology.md)
 
+## Related packages
+
+- [bounded_authority_protocol (monorepo)](https://github.com/baselabs/bounded_authority_protocol) —
+  the protocol source: specifications, ADRs, the certified conformance corpora this
+  package vendors, and the reference Elixir implementation.
+- [@bounded-authority-protocol/signer](https://www.npmjs.com/package/@bounded-authority-protocol/signer) —
+  the holder/issuer companion: signs proofs, grants, boundary anchors, and key
+  transitions through a caller-owned key handle. This verifier holds no private keys;
+  the signer produces the bytes it checks (see [Pairing with the signer](#pairing-with-the-signer)).
+- This package on npm:
+  [@bounded-authority-protocol/verifier](https://www.npmjs.com/package/@bounded-authority-protocol/verifier).
+
 ## Development
 
 ```bash
@@ -176,6 +287,7 @@ pnpm test                    # unit + struct + façade corpus-vector tests
 pnpm test:permissiveness     # the mutation gate
 pnpm conformance             # 283/283 + key census (vendored v1 snapshot)
 pnpm conformance:v2          # 268/268 + key census (vendored v2 snapshot)
+pnpm check:currency          # dependency-currency gate (latest-first)
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bounded-authority-protocol/verifier",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Provider-neutral, deterministic verifier SDK for bounded proof-of-possession authority — a typed TypeScript reimplementation of the Bounded Authority Protocol verification profiles (wire contract-majors 1 and 2).",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,6 +20,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "license-check": "node tools/license-check.mjs",
+    "check:currency": "node tools/check-currency.mjs",
     "test": "node --test --import tsx/esm test/*.test.ts",
     "test:permissiveness": "node --test --import tsx/esm test/permissiveness.ts",
     "conformance": "tsx conformance/run.ts",
@@ -27,11 +28,12 @@
     "census": "tsx conformance/census.ts"
   },
   "devDependencies": {
-    "@types/node": "^26.4.0",
-    "eslint": "^10.9.1",
-    "tsx": "^4.23.12",
+    "@types/node": "^26.6.1",
+    "eslint": "^10.10.0",
+    "semver": "^7.8.5",
+    "tsx": "^4.23.13",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.68.0"
+    "typescript-eslint": "^8.70.0"
   },
   "repository": {
     "type": "git",