pazair-verify 1.10.0 → 1.11.0

package/README.md

@@ -131,6 +131,7 @@ console.log(await verifyReceipt(receipt, { delivery }));
 | `verifyCredential(vc, { fetch?, didDocument?, keysDocument?, now? })` | Section 18: the pass as a W3C Verifiable Credential: VC 2.0, the did:web resolved, the `eddsa-jcs-2022` proof, the subject on the issuer's origin, `validFrom`/`validUntil`, the pass inside; a verdict and a sentence |
 | `verifyDataIntegrity(doc, didDocument)` / `signDataIntegrity(doc, privateKey, verificationMethod, created?)` | any W3C Data Integrity proof with `eddsa-jcs-2022`, checked or made (the W3C Recommendation's vector holds) |
 | `resolveDidWeb(did, fetch?)`, `didWebUrl(did)`, `multikeyOf(x)`, `multikeyToX(multibase)`, `base58btcEncode`/`base58btcDecode` | did:web, Multikey (Ed25519) and base58btc, the pieces of section 18 |
+| `verifyLicence(licence, { keys?, pqKeys?, now? })` / `checkLicence(url, { fetch?, now? })` | Section 19, the buyer's licence from an apprenticeship: both signatures, the rules of its level (a signed licence under its pass mark is invalid), whether it is current; `checkLicence` reads a licence URL against the issuer's own keys (`npx pazair-verify licence <url>`) |
 | `leafOf(pass)`, `canonical(obj)`, `sha256hex(s)` | the building blocks of the spec |
 | `fetchKeys(origin?)` | the issuer's keys from `/.well-known/pazair-receipts.json` |
 

package/bin/cli.js

@@ -3,9 +3,10 @@
 // npx pazair-verify remember [origin] [--json]: Remember, the issuer's chain of daily roots, recomputed here.
 // npx pazair-verify witness <day:head> [origin] [--json]: a head you kept, against the chain you recompute.
 // npx pazair-verify credential <credential url or file> [--json]: the Word Pass as a W3C Verifiable Credential (SPEC 18), then its anchors.
+// npx pazair-verify licence <licence url> [--json]: the buyer's licence from the apprenticeship (SPEC 19), against the issuer's keys.
 // Exit codes: 0 trusted / consistent, 1 invalid / inconsistent (do not rely on it), 2 usage, 3 unreachable (could not check).
 import { readFileSync } from 'node:fs';
-import { checkHead, checkRemember, checkWordPass, verifyCredential } from '../src/index.js';
+import { checkHead, checkLicence, checkRemember, checkWordPass, verifyCredential } from '../src/index.js';
 
 const args = process.argv.slice(2);
 if (args.includes('-v') || args.includes('--version')) {
@@ -15,10 +16,10 @@ if (args.includes('-v') || args.includes('--version')) {
 const words = args.filter((a) => !a.startsWith('-'));
 const help = args.includes('-h') || args.includes('--help');
 const json = args.includes('--json');
-const usage = 'Usage: npx pazair-verify <word pass url> [--json]\n       npx pazair-verify remember [origin] [--json]\n       npx pazair-verify witness <day:head> [origin] [--json]\n       npx pazair-verify credential <credential url or file> [--json]\nExamples: npx pazair-verify https://pazair.kulalabs.ch/v1/agents/ag_xyz/pass\n          npx pazair-verify remember https://pazair.kulalabs.ch\n          npx pazair-verify witness 2026-10-10:3f9c… https://pazair.kulalabs.ch\n          npx pazair-verify credential https://pazair.ch/v1/agents/ag_xyz/pass.vc';
+const usage = 'Usage: npx pazair-verify <word pass url> [--json]\n       npx pazair-verify remember [origin] [--json]\n       npx pazair-verify witness <day:head> [origin] [--json]\n       npx pazair-verify credential <credential url or file> [--json]\n       npx pazair-verify licence <licence url> [--json]\nExamples: npx pazair-verify https://pazair.kulalabs.ch/v1/agents/ag_xyz/pass\n          npx pazair-verify remember https://pazair.kulalabs.ch\n          npx pazair-verify witness 2026-10-10:3f9c… https://pazair.kulalabs.ch\n          npx pazair-verify credential https://pazair.ch/v1/agents/ag_xyz/pass.vc\n          npx pazair-verify licence https://pazair.ch/v1/agents/ag_xyz/licence';
 if (!words.length || help) { (help ? console.log : console.error)(usage); process.exit(help ? 0 : 2); }
 const clean = (s) => String(s).replace(/[\u0000-\u001f\u007f-\u009f]/g, '?'); // nothing from the network rewrites your terminal
-const codes = { valid: 0, consistent: 0, kept_its_word: 0, no_badge_yet: 0, signed_unanchored: 0, inconsistent: 1, invalid: 1, unreachable: 3 };
+const codes = { valid: 0, consistent: 0, expired: 1, none: 1, kept_its_word: 0, no_badge_yet: 0, signed_unanchored: 0, inconsistent: 1, invalid: 1, unreachable: 3 };
 
 if (words[0] === 'remember') {
   const r = await checkRemember(words[1] ?? 'https://pazair.kulalabs.ch');
@@ -48,6 +49,13 @@ if (words[0] === 'credential') {
   if (json) console.log(JSON.stringify({ ...r, anchors: anchors ? { ...anchors, pass: undefined } : null }, null, 2));
   process.exit(!r.valid ? (codes[r.trust] ?? 1) : (codes[anchors.trust] ?? 1));
 }
+if (words[0] === 'licence' || words[0] === 'license') {
+  if (!words[1]) { console.error(usage); process.exit(2); }
+  const r = await checkLicence(words[1]);
+  console.log(clean(r.say));
+  if (json) console.log(JSON.stringify(r, null, 2));
+  process.exit(codes[r.verdict] ?? 1);
+}
 const r = await checkWordPass(words[0]);
 console.log(clean(r.say));
 if (json) console.log(JSON.stringify({ ...r, pass: undefined }, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pazair-verify",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Verify Word Passes, receipts, Merkle proofs and Remember (the chain of daily roots, Ed25519 + ML-DSA-65): checked by anyone, for any issuer, without trusting it. Zero dependencies.",
   "type": "module",
   "main": "./src/index.js",

package/src/index.d.ts

@@ -88,3 +88,11 @@ export type CredentialCheck = {
   pass: Awaited<ReturnType<typeof verifyPass>> | null; same_key: boolean | null;
 };
 export function verifyCredential(vc: unknown, opts?: { fetch?: typeof fetch; didDocument?: DidDocument; keysDocument?: { keys: Jwk[]; pq_keys?: PqKey[] }; now?: number }): Promise<CredentialCheck>;
+
+// The buyer's licence (SPEC section 19, the apprenticeship).
+export const LICENCE_LEVELS: Record<'basic' | 'professional' | 'critical', { tasks: number; need: number; valid_days: number }>;
+export type LicenceCheck = { valid: boolean; current: boolean; signature_valid: boolean; pq_signed: boolean; ml_dsa_65: boolean | null; rules_hold: boolean; level: string | null; agent: string | null; valid_until: string | null };
+/** Section 19: both signatures and the rules of its level; `current` says whether it has expired. */
+export function verifyLicence(licence: unknown, opts?: { keys?: Jwk[]; pqKeys?: PqKey[]; now?: Date }): Promise<LicenceCheck>;
+/** Section 19: a licence URL checked against the issuer's own keys. */
+export function checkLicence(url: string, opts?: { fetch?: typeof fetch; now?: Date }): Promise<{ verdict: 'valid' | 'expired' | 'none' | 'invalid' | 'unreachable'; agent?: string | null; level?: string; say: string; licences: LicenceCheck[] }>;

package/src/index.js

@@ -404,3 +404,50 @@ export { FINGERPRINT, rsEncode, fingerprintOf, fingerprintDistance, fingerprintS
 
 // The Word Pass as a W3C Verifiable Credential 2.0 (SPEC section 18): did:web, Multikey, Data Integrity eddsa-jcs-2022.
 export { base58btcEncode, base58btcDecode, multikeyOf, multikeyToX, didWebUrl, resolveDidWeb, verifyDataIntegrity, verifyCredential, signDataIntegrity } from './credential.js';
+
+// The buyer's licence (SPEC section 19, the apprenticeship): an agent passed an exam of buying for someone else.
+/** Section 19: the levels: tasks in the exam, the pass mark, the days a licence is valid. */
+export const LICENCE_LEVELS = { basic: { tasks: 5, need: 4, valid_days: 365 }, professional: { tasks: 8, need: 7, valid_days: 180 }, critical: { tasks: 10, need: 10, valid_days: 90 } };
+
+/**
+ * Section 19: a buyer's licence. Both signatures, and the rules of its level: the score reaches the pass mark, the
+ * tasks match the level, and it is valid no longer than the level allows. A signed licence that breaks its own level's
+ * rules is invalid. `current` says whether it has expired; an expired licence is genuine but no longer shows anything.
+ */
+export async function verifyLicence(licence, { keys, pqKeys, now = new Date() } = {}) {
+  keys ??= await fetchKeys();
+  const l = licence && typeof licence === 'object' ? licence : {}, lv = LICENCE_LEVELS[l.level];
+  const signature_valid = l.kind === 'buyer_licence' && typeof l.issuer === 'string' && (await verifySignature(l, keys));
+  const pq = await verifyPqSignature(l, pqKeys);
+  const [right, of] = String(l.score ?? '').split('/').map(Number);
+  const days = (Date.parse(l.valid_until) - Date.parse(l.issued_at)) / 864e5;
+  const rules_hold = !!lv && of === lv.tasks && right >= lv.need && right <= of && Array.isArray(l.tasks) && l.tasks.length === of && days > 0 && days <= lv.valid_days;
+  const current = typeof l.valid_until === 'string' && l.valid_until > now.toISOString();
+  return { valid: signature_valid && pq.valid !== false && rules_hold, current, signature_valid, pq_signed: pq.signed, ml_dsa_65: pq.valid, rules_hold, level: l.level ?? null, agent: l.agent ?? null, valid_until: l.valid_until ?? null };
+}
+
+/**
+ * Section 19: "Has this agent passed the apprenticeship?", from a licence URL (e.g. <origin>/v1/agents/<id>/licence),
+ * checked against the issuer's own keys. verdict: valid (a current licence), expired, none, invalid or unreachable.
+ */
+export async function checkLicence(url, { fetch: f = fetch, now = new Date() } = {}) {
+  let u; try { u = new URL(url); } catch { return { verdict: 'invalid', say: 'Not a URL.', licences: [] }; }
+  if (u.protocol !== 'https:') return { verdict: 'invalid', say: 'Only https URLs are checked.', licences: [] };
+  let doc, kd;
+  try { const r = await f(u.href, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(8000) }); if (!r.ok) throw new Error(); doc = await r.json(); }
+  catch { return { verdict: 'unreachable', say: `No licence could be read at ${u.host}.`, licences: [] }; }
+  try { kd = await fetchKeysDocument(u.origin, f); } catch { return { verdict: 'unreachable', say: `${u.host} publishes no keys at /.well-known/pazair-receipts.json.`, licences: [] }; }
+  const list = Array.isArray(doc?.licences) ? doc.licences.map((x) => x?.licence ?? x) : doc?.kind === 'buyer_licence' ? [doc] : [];
+  const agent = typeof doc?.agent_id === 'string' ? doc.agent_id : list[0]?.agent ?? null;
+  const licences = await Promise.all(list.map(async (l) => {
+    const v = await verifyLicence(l, { keys: kd.keys, pqKeys: kd.pq_keys, now });
+    // A licence for another agent, served under this one, proves nothing about this one.
+    return agent && l?.agent !== agent ? { ...v, valid: false, rules_hold: false } : v;
+  }));
+  const day = (t) => String(t ?? '').slice(0, 10);
+  if (!licences.length) return { verdict: 'none', agent, say: `${agent ?? 'This agent'} holds no buyer's licence from ${u.host}.`, licences };
+  if (licences.some((v) => !v.valid)) return { verdict: 'invalid', agent, say: `Do not rely on it: a licence from ${u.host} does not verify against the issuer's keys or breaks its level's rules.`, licences };
+  const best = [...licences].reverse().find((v) => v.current);
+  if (!best) return { verdict: 'expired', agent, say: `${agent}: every buyer's licence from ${u.host} has expired (the last on ${day(licences.at(-1).valid_until)}).`, licences };
+  return { verdict: 'valid', agent, level: best.level, say: `${agent}: ${best.level} buyer's licence from ${u.host}, signatures valid${best.ml_dsa_65 ? ' (Ed25519 and ML-DSA-65)' : ''}, current until ${day(best.valid_until)}. It shows the exam was passed that day; it is no regulatory certification.`, licences };
+}