@holdyourvoice/hyv 3.1.1 → 3.3.0

package/dist/ai-editor.test.js

@@ -1,15 +1,73 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { analyzeAiEditor, rules } from './ai-editor.js';
+import { analyzeAiEditor, RULESET_VERSION, rules, serializedRules } from './ai-editor.js';
+import { createHash } from 'node:crypto';
 test('publishes executable rules with stable IDs and repair directions', () => {
-    assert.ok(rules.length > 0);
+    assert.equal(RULESET_VERSION, '3.2.0-reconciled.1');
+    assert.equal(rules.length, 148);
+    assert.equal(createHash('sha256').update(JSON.stringify(rules.map((rule) => rule.id))).digest('hex'), '8d3cdde1922686076cb3baa79c55db95f37c9088d246f47c24405417fe58f979');
+    assert.equal(createHash('sha256').update(JSON.stringify(serializedRules())).digest('hex'), 'a758d7cd8e53e42d1a3ada81aff3e61f2994555d286f8915a9fc52767f145094');
+    assert.equal(new Set(rules.map((rule) => rule.id)).size, rules.length);
     for (const rule of rules) {
-        assert.match(rule.id, /^ai\./);
+        assert.match(rule.id, /^(ai|formula|hedge|struct|punct|bait|cringe|insider|ogilvy)\./);
         assert.ok(rule.reason.length > 0);
         assert.ok(rule.suggestion.length > 0);
+        assert.equal(rule.expression.global, false, rule.id);
+        assert.equal(rule.expression.sticky, false, rule.id);
     }
 });
-test('detects every executable rule against its exact sentence', () => {
+function profileWithPolicies(rulePolicy) {
+    return {
+        version: '3', id: 'founder.test', revision: 1, revisionDigest: '0'.repeat(64), sampleCount: 2,
+        metrics: { sentenceLength: 5, sentenceVariation: 1, sentenceStructure: [], rhythm: 1, paragraphLength: 1, openingMoves: [], vocabulary: [], lexicalDensity: 0.5, pointOfView: 'mixed', punctuation: {}, caseStyle: 'mixed', questionRate: 0, transitions: [] },
+        avoid: [], provenance: { source: 'test', rights: 'test', createdAt: '2026-08-13T00:00:00.000Z' }, rulePolicy,
+        fingerprint: { contractionRate: 0, sentenceLengthDistribution: { short: 1, medium: 0, long: 0 }, bulletRate: 0, enDashRate: 0 },
+        tolerances: { contractionRate: { absolute: 0, calibrated: false }, sentenceLengthDistribution: { absolute: 0, calibrated: false }, bulletRate: { absolute: 0, calibrated: false }, enDashRate: { absolute: 0, calibrated: false } },
+        metricFixtures: { contractionRate: ['test'], sentenceLengthDistribution: ['test'], bulletRate: ['test'], enDashRate: ['test'] },
+    };
+}
+test('applies all four v3 policy states after matching and preserves catalog order', () => {
+    const report = analyzeAiEditor('Firstly, perhaps we leverage a holistic plan.', profileWithPolicies({
+        'formula.firstly': 'blocking',
+        'hedge.perhaps': 'advisory',
+        'ai.leverage': 'judgment-required',
+        'ai.holistic': 'disabled',
+    }));
+    assert.deepEqual(report.findings.map((finding) => [finding.id, finding.appliedPolicy, finding.severity]), [
+        ['ai.leverage', 'judgment-required', 'yellow'],
+        ['formula.firstly', 'blocking', 'red'],
+        ['hedge.perhaps', 'advisory', 'yellow'],
+    ]);
+    assert.equal(report.passed, false);
+});
+test('fails closed when a v3 policy names a rule outside the catalog', () => {
+    assert.throws(() => analyzeAiEditor('Plain text.', profileWithPolicies({ 'ai.missing': 'blocking' })), /unknown rule ID/);
+});
+test('uses reconciled defaults for v2 profiles and suppresses inherited duplicate emissions', () => {
+    const report = analyzeAiEditor("It's worth noting: in other words, I think the same plan. Better results.");
+    assert.equal(report.findings.some((finding) => finding.id === 'hedge.worth-noting'), false);
+    assert.equal(report.findings.some((finding) => finding.id === 'struct.in-other-words'), false);
+    assert.equal(report.findings.some((finding) => finding.id === 'hedge.i-think'), false);
+    assert.equal(report.findings.some((finding) => finding.id === 'struct.same-better'), false);
+    assert.ok(report.findings.every((finding) => finding.appliedPolicy !== undefined));
+});
+test('treats bare red vocabulary as pending judgment and clear sincerity or dashes as blocking', () => {
+    const vocabulary = analyzeAiEditor('We leverage the existing scheduler.');
+    assert.deepEqual(vocabulary.findings.find((finding) => finding.id === 'ai.leverage')?.appliedPolicy, 'judgment-required');
+    assert.equal(vocabulary.passed, true);
+    const blocked = analyzeAiEditor('To be honest, the scheduler failed — twice.');
+    assert.ok(blocked.findings.some((finding) => finding.id === 'formula.performative-sincerity' && finding.appliedPolicy === 'blocking'));
+    assert.ok(blocked.findings.some((finding) => finding.id === 'punct.em-dash' && finding.appliedPolicy === 'blocking'));
+    assert.equal(blocked.passed, false);
+    const advisory = analyzeAiEditor('Honestly, the scheduler failed twice.');
+    assert.ok(advisory.findings.some((finding) => finding.id === 'hedge.performative-sincerity-adverb' && finding.appliedPolicy === 'advisory'));
+    assert.equal(advisory.passed, true);
+});
+test('only applies the question-hook policy to document sentence one', () => {
+    assert.ok(analyzeAiEditor('Have you checked the invoice? It is overdue.').findings.some((finding) => finding.id === 'ai.question-hook'));
+    assert.equal(analyzeAiEditor('The invoice is overdue. Have you checked it?').findings.some((finding) => finding.id === 'ai.question-hook'), false);
+});
+test('detects representative rules from every inherited rule family', () => {
     const examples = [
         ['ai.delve', 'we will delve into it.'],
         ['ai.leverage', 'we leverage the existing logs.'],
@@ -18,21 +76,23 @@ test('detects every executable rule against its exact sentence', () => {
         ['ai.robust', 'robust evidence supports the claim.'],
         ['ai.landscape', 'the market landscape changed.'],
         ['ai.game-changer', 'this is a game-changer.'],
-        ['ai.formulaic-connector', 'Firstly, check the invoice.'],
-        ['ai.hedging', 'Perhaps the invoice is late.'],
-        ['ai.signpost', 'This is why the invoice matters.'],
-        ['ai.not-just', 'this is not just fast but reliable.'],
-        ['ai.truth-setup', 'the hard truth is in the logs.'],
-        ['ai.em-dash', 'the logs failed — retry later.'],
-        ['ai.question-hook', 'Have you checked the logs?'],
-        ['ai.abstract-cluster', 'alignment and clarity are missing.'],
+        ['formula.firstly', 'Firstly, check the invoice.'],
+        ['hedge.perhaps', 'Perhaps the invoice is late.'],
+        ['struct.this-is-why', 'This is why the invoice matters.'],
+        ['struct.not-just-but-also', 'this is not just fast but reliable.'],
+        ['struct.rhetorical-truth', 'the hard truth is in the logs.'],
+        ['punct.em-dash', 'the logs failed — retry later.'],
+        ['bait.let-that-sink', 'Let that sink in.'],
+        ['cringe.10x', 'The change delivered a 10x result.'],
+        ['insider.nobody-tells', 'What nobody tells you is in the report.'],
+        ['ogilvy.bandwidth', 'We lack the bandwidth this week.'],
     ];
     for (const [id, example] of examples) {
         const report = analyzeAiEditor(example);
-        assert.deepEqual(report.findings.map((finding) => [finding.id, finding.sentence]), [[id, 1]], id);
+        assert.ok(report.findings.some((finding) => finding.id === id && finding.sentence === 1), id);
     }
 });
-test('keeps a counterexample for every executable rule', () => {
+test('keeps counterexamples for representative inherited rules', () => {
     const counterexamples = [
         ['ai.delve', 'we inspect the logs.'],
         ['ai.leverage', 'we use the existing logs.'],
@@ -41,14 +101,16 @@ test('keeps a counterexample for every executable rule', () => {
         ['ai.robust', 'the evidence includes three dated reports.'],
         ['ai.landscape', 'the market changed after the price cut.'],
         ['ai.game-changer', 'the release removed a manual step.'],
-        ['ai.formulaic-connector', 'next, check the invoice.'],
-        ['ai.hedging', 'the invoice is late.'],
-        ['ai.signpost', 'the invoice matters because it is overdue.'],
-        ['ai.not-just', 'the service is fast and reliable.'],
-        ['ai.truth-setup', 'the logs show the service failed.'],
-        ['ai.em-dash', 'the logs failed; retry later.'],
-        ['ai.question-hook', 'the reviewer asked, have you checked the logs?'],
-        ['ai.abstract-cluster', 'the editor checked the contract and sent the invoice.'],
+        ['formula.firstly', 'next, check the invoice.'],
+        ['hedge.perhaps', 'the invoice is late.'],
+        ['struct.this-is-why', 'the invoice matters because it is overdue.'],
+        ['struct.not-just-but-also', 'the service is fast and reliable.'],
+        ['struct.rhetorical-truth', 'the logs show the service failed.'],
+        ['punct.em-dash', 'the logs failed; retry later.'],
+        ['bait.let-that-sink', 'The invoice is overdue.'],
+        ['cringe.10x', 'The result rose from 2 to 20.'],
+        ['insider.nobody-tells', 'The report explains the missing step.'],
+        ['ogilvy.bandwidth', 'We lack time this week.'],
     ];
     for (const [id, example] of counterexamples) {
         assert.equal(analyzeAiEditor(example).findings.some((finding) => finding.id === id), false, id);
@@ -59,3 +121,54 @@ test('keeps yellow findings as review cues rather than release blockers', () =>
     assert.ok(report.findings.every((finding) => finding.severity === 'yellow'));
     assert.equal(report.passed, true);
 });
+test('restores the benchmark signals from the 2.9.24 executable catalog', () => {
+    const report = analyzeAiEditor("This work is meaningful. Here's the part nobody is talking about. The change delivered a 10x result.");
+    assert.deepEqual(report.findings.map((finding) => [finding.id, finding.sentence]), [
+        ['ai.meaningful', 1],
+        ['struct.heres-where', 2],
+        ['cringe.10x', 3],
+    ]);
+});
+test('returns the same findings across repeated sentence and line analysis', () => {
+    for (const text of ['We leverage logs. We leverage traces.', 'No demos. No decks. No distractions. Same team. Better results.']) {
+        assert.deepEqual(analyzeAiEditor(text), analyzeAiEditor(text));
+    }
+});
+test('reports the same rule in multiple sentences', () => {
+    const report = analyzeAiEditor('We leverage logs. We leverage traces.');
+    assert.deepEqual(report.findings.filter((finding) => finding.id === 'ai.leverage').map((finding) => finding.sentence), [1, 2]);
+});
+test('executes inherited cross-sentence rules and maps them to the first sentence', () => {
+    const report = analyzeAiEditor('No demos. No decks. No distractions. Same team. Better results.');
+    assert.deepEqual(report.findings
+        .filter((finding) => finding.id === 'struct.negation-cascade' || finding.id === 'struct.same-better')
+        .map((finding) => [finding.id, finding.sentence]), [['struct.negation-cascade', 1]]);
+});
+test('preserves inherited physical-line matching and line-start anchors', () => {
+    const sameLine = analyzeAiEditor("This isn't positioning. This is proof. Forget vanity metrics. You need retention.");
+    assert.ok(sameLine.findings.some((finding) => finding.id === 'struct.this-isnt-x-this-is-y'));
+    assert.ok(sameLine.findings.some((finding) => finding.id === 'struct.forget-x'));
+    assert.equal(analyzeAiEditor("This isn't positioning.\nThis is proof.").findings.some((finding) => finding.id === 'struct.this-isnt-x-this-is-y'), false);
+    assert.equal(analyzeAiEditor('The logs failed. Of course we can retry.').findings.some((finding) => finding.id === 'cringe.of-course'), false);
+    assert.ok(analyzeAiEditor('The logs failed.\nOf course we can retry.').findings.some((finding) => finding.id === 'cringe.of-course'));
+});
+test('retains the current question-hook and abstract-cluster detectors', () => {
+    assert.ok(analyzeAiEditor('Have you checked the invoice?').findings.some((finding) => finding.id === 'ai.question-hook'));
+    assert.ok(analyzeAiEditor('Clarity and strategy are missing.').findings.some((finding) => finding.id === 'ai.abstract-cluster'));
+});
+test('serializes reconstructable regular expressions and explicit scopes', () => {
+    const catalog = serializedRules();
+    assert.equal(catalog.length, 148);
+    assert.ok(catalog.every((rule) => rule.scope === 'sentence' || rule.scope === 'line'));
+    const meaningful = catalog.find((rule) => rule.id === 'ai.meaningful');
+    assert.ok(meaningful);
+    assert.equal(new RegExp(meaningful.expression.source, meaningful.expression.flags).test('Meaningful work.'), true);
+});
+test('suppresses intentional inherited overlaps before scoring', () => {
+    const report = analyzeAiEditor('In other words, use logs.');
+    assert.deepEqual(report.findings.map((finding) => finding.id), ['formula.in-other-words']);
+    assert.equal(report.score, 82);
+});
+test('returns zero AI findings for clean input', () => {
+    assert.deepEqual(analyzeAiEditor('The launch starts Tuesday. The owner signed the release checklist.').findings, []);
+});

package/dist/approval-capability.js

@@ -0,0 +1,111 @@
+import { createHash, createPublicKey, verify } from 'node:crypto';
+import { parseCanonicalJson } from './canonical-json.js';
+const DIGEST = /^[a-f0-9]{64}$/;
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+const CLAIM_KEYS = ['version', 'purpose', 'issuer', 'audience', 'subjectArtifactFingerprint', 'sourceHash', 'candidateHash', 'profileId', 'profileRevisionDigest', 'keyId', 'issuedAt', 'notBefore', 'expiresAt', 'nonce'];
+const STORE_KEYS = ['version', 'audience', 'maxCapabilityLifetimeSeconds', 'keys'];
+function fail(error) { return { ok: false, error }; }
+function plain(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype; }
+function exactKeys(value, required, optional = []) {
+    return required.every((key) => key in value) && Object.keys(value).every((key) => required.includes(key) || optional.includes(key));
+}
+function bounded(value) { return typeof value === 'string' && value.length > 0 && value.length <= 128; }
+function safeTime(value) { return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0; }
+function validClaims(value) {
+    if (!plain(value) || !exactKeys(value, CLAIM_KEYS))
+        return false;
+    return bounded(value.issuer) && bounded(value.keyId) && bounded(value.profileId) && bounded(value.nonce)
+        && typeof value.version === 'string' && typeof value.purpose === 'string' && typeof value.audience === 'string'
+        && [value.subjectArtifactFingerprint, value.sourceHash, value.candidateHash].every((item) => typeof item === 'string' && DIGEST.test(item)) && bounded(value.profileRevisionDigest)
+        && safeTime(value.issuedAt) && safeTime(value.notBefore) && safeTime(value.expiresAt);
+}
+export function parseApprovalTrustStore(value) {
+    if (!plain(value) || !exactKeys(value, STORE_KEYS) || value.version !== '1' || value.audience !== '@holdyourvoice/hyv'
+        || !Number.isSafeInteger(value.maxCapabilityLifetimeSeconds) || value.maxCapabilityLifetimeSeconds < 1 || value.maxCapabilityLifetimeSeconds > 86400 || !Array.isArray(value.keys) || value.keys.length > 128)
+        return undefined;
+    const pairs = new Set();
+    for (const item of value.keys) {
+        if (!plain(item) || !exactKeys(item, ['issuer', 'keyId', 'publicKeySpki', 'status'], ['activeFrom', 'activeUntil']) || !bounded(item.issuer) || !bounded(item.keyId)
+            || typeof item.publicKeySpki !== 'string' || !BASE64URL.test(item.publicKeySpki) || !['active', 'revoked'].includes(item.status)
+            || (item.activeFrom !== undefined && !safeTime(item.activeFrom)) || (item.activeUntil !== undefined && !safeTime(item.activeUntil)))
+            return undefined;
+        const pair = `${item.issuer}\0${item.keyId}`;
+        if (pairs.has(pair))
+            return undefined;
+        pairs.add(pair);
+        try {
+            if (item.publicKeySpki.length > 128)
+                return undefined;
+            const der = Buffer.from(item.publicKeySpki, 'base64url');
+            const key = createPublicKey({ key: der, format: 'der', type: 'spki' });
+            if (der.length !== 44 || key.asymmetricKeyType !== 'ed25519')
+                return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return value;
+}
+export function verifyApprovalCapability(envelope, trustValue, expected) {
+    if (!safeTime(expected.now))
+        return fail('invalid_schema');
+    if (!plain(envelope) || !exactKeys(envelope, ['payload', 'signature']) || typeof envelope.payload !== 'string' || typeof envelope.signature !== 'string'
+        || !BASE64URL.test(envelope.payload) || !BASE64URL.test(envelope.signature))
+        return fail('invalid_encoding');
+    if (envelope.payload.length > 5462 || envelope.signature.length !== 86)
+        return fail('size_exceeded');
+    const payload = Buffer.from(envelope.payload, 'base64url');
+    const signature = Buffer.from(envelope.signature, 'base64url');
+    if (payload.length > 4096 || signature.length !== 64)
+        return fail('size_exceeded');
+    if (payload.toString('base64url') !== envelope.payload || signature.toString('base64url') !== envelope.signature)
+        return fail('invalid_encoding');
+    let parsed;
+    try {
+        parsed = parseCanonicalJson(payload);
+    }
+    catch (error) {
+        return fail(error instanceof Error && /canonical/i.test(error.message) ? 'non_canonical' : 'invalid_schema');
+    }
+    if (!validClaims(parsed))
+        return fail('invalid_schema');
+    const claims = parsed;
+    if (claims.version !== '1')
+        return fail('wrong_version');
+    if (claims.purpose !== expected.expectedPurpose)
+        return fail('wrong_purpose');
+    if (claims.audience !== '@holdyourvoice/hyv')
+        return fail('wrong_audience');
+    if (claims.subjectArtifactFingerprint !== expected.expectedSubjectArtifactFingerprint || claims.sourceHash !== expected.binding.sourceHash || claims.candidateHash !== expected.binding.candidateHash || claims.profileId !== expected.binding.profileId || claims.profileRevisionDigest !== expected.binding.profileRevisionDigest)
+        return fail('binding_mismatch');
+    const trustStore = parseApprovalTrustStore(trustValue);
+    if (!trustStore)
+        return fail('invalid_schema');
+    if (claims.audience !== trustStore.audience)
+        return fail('wrong_audience');
+    const key = trustStore.keys.find((item) => item.issuer === claims.issuer && item.keyId === claims.keyId);
+    if (!key)
+        return fail('unknown_key');
+    if (key.status === 'revoked')
+        return fail('revoked_key');
+    if ((key.activeFrom !== undefined && (claims.issuedAt < key.activeFrom || expected.now < key.activeFrom)) || (key.activeUntil !== undefined && (claims.issuedAt >= key.activeUntil || expected.now >= key.activeUntil)))
+        return fail('inactive_key');
+    if (!(claims.issuedAt <= claims.notBefore && claims.notBefore < claims.expiresAt))
+        return fail('invalid_schema');
+    if (claims.expiresAt - claims.issuedAt > trustStore.maxCapabilityLifetimeSeconds)
+        return fail('lifetime_exceeded');
+    if (expected.now < claims.notBefore)
+        return fail('premature');
+    if (expected.now >= claims.expiresAt)
+        return fail('expired');
+    try {
+        const publicKey = createPublicKey({ key: Buffer.from(key.publicKeySpki, 'base64url'), format: 'der', type: 'spki' });
+        if (!verify(null, payload, publicKey, signature))
+            return fail('invalid_signature');
+    }
+    catch {
+        return fail('invalid_signature');
+    }
+    return { ok: true, capabilityFingerprint: createHash('sha256').update('hyv:approval-capability:v1\0').update(payload).update(signature).digest('hex') };
+}

package/dist/approval-capability.test.js

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict';
+import { generateKeyPairSync, sign } from 'node:crypto';
+import test from 'node:test';
+import { canonicalJsonBytes } from './canonical-json.js';
+import { verifyApprovalCapability } from './approval-capability.js';
+const binding = {
+    rewriteTaskFingerprint: '1'.repeat(64), rewriteResponseFingerprint: '2'.repeat(64), deterministicArtifactFingerprint: '3'.repeat(64),
+    sourceHash: '4'.repeat(64), candidateHash: '5'.repeat(64), profileId: 'founder.primary', profileRevisionDigest: '6'.repeat(64),
+    rulesetVersion: '3.2.0', schemaVersion: '1',
+};
+const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+const publicKeySpki = publicKey.export({ format: 'der', type: 'spki' }).toString('base64url');
+const trustStore = { version: '1', audience: '@holdyourvoice/hyv', maxCapabilityLifetimeSeconds: 300, keys: [{ issuer: 'host.example', keyId: 'key-1', publicKeySpki, status: 'active' }] };
+function envelope(overrides = {}, signer = privateKey) {
+    const claims = {
+        version: '1', purpose: 'hyv.final-approval', issuer: 'host.example', audience: '@holdyourvoice/hyv',
+        subjectArtifactFingerprint: '7'.repeat(64), sourceHash: binding.sourceHash, candidateHash: binding.candidateHash,
+        profileId: binding.profileId, profileRevisionDigest: binding.profileRevisionDigest, keyId: 'key-1',
+        issuedAt: 100, notBefore: 100, expiresAt: 200, nonce: 'nonce-1', ...overrides,
+    };
+    const payload = canonicalJsonBytes(claims);
+    return { payload: payload.toString('base64url'), signature: sign(null, payload, signer).toString('base64url') };
+}
+test('verifies one canonical bound Ed25519 final-approval capability', () => {
+    const result = verifyApprovalCapability(envelope(), trustStore, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' });
+    assert.equal(result.ok, true);
+    if (result.ok)
+        assert.match(result.capabilityFingerprint, /^[a-f0-9]{64}$/);
+});
+test('fails closed for purpose, binding, trust, time, signature, and canonical encoding', () => {
+    assert.deepEqual(verifyApprovalCapability(envelope({ purpose: 'hyv.rebuild-authorization' }), trustStore, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'wrong_purpose' });
+    assert.deepEqual(verifyApprovalCapability(envelope({ candidateHash: '8'.repeat(64) }), trustStore, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'binding_mismatch' });
+    assert.deepEqual(verifyApprovalCapability(envelope(), { ...trustStore, keys: [{ ...trustStore.keys[0], status: 'revoked' }] }, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'revoked_key' });
+    assert.deepEqual(verifyApprovalCapability(envelope(), trustStore, { now: 201, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'expired' });
+    const forged = envelope();
+    const forgedBytes = Buffer.from(forged.signature, 'base64url');
+    forgedBytes[0] = forgedBytes[0] ^ 1;
+    forged.signature = forgedBytes.toString('base64url');
+    assert.deepEqual(verifyApprovalCapability(forged, trustStore, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'invalid_signature' });
+    const nonCanonical = envelope();
+    nonCanonical.payload = Buffer.from(` ${Buffer.from(nonCanonical.payload, 'base64url').toString('utf8')}`).toString('base64url');
+    assert.deepEqual(verifyApprovalCapability(nonCanonical, trustStore, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'non_canonical' });
+});
+test('rejects malformed envelopes and invalid trust stores without returning secret material', () => {
+    const result = verifyApprovalCapability({ payload: `${envelope().payload}=`, signature: envelope().signature }, trustStore, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' });
+    assert.deepEqual(result, { ok: false, error: 'invalid_encoding' });
+    assert.doesNotMatch(JSON.stringify(result), /nonce-1|signature|publicKeySpki/);
+    assert.deepEqual(verifyApprovalCapability(envelope(), { ...trustStore, keys: [...trustStore.keys, trustStore.keys[0]] }, { now: 150, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'invalid_schema' });
+});
+test('rejects an invalid host clock', () => {
+    assert.deepEqual(verifyApprovalCapability(envelope(), trustStore, { now: Number.NaN, expectedSubjectArtifactFingerprint: '7'.repeat(64), binding, expectedPurpose: 'hyv.final-approval' }), { ok: false, error: 'invalid_schema' });
+});

package/dist/approval-context.js

@@ -0,0 +1,54 @@
+import { closeSync, constants, fstatSync, openSync, readSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { join } from 'node:path';
+import { parseApprovalTrustStore } from './approval-capability.js';
+const MAX_BYTES = 1024 * 1024;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+function readBounded(descriptor) {
+    const chunks = [];
+    let size = 0;
+    while (size <= MAX_BYTES) {
+        const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, MAX_BYTES + 1 - size));
+        const count = readSync(descriptor, chunk, 0, chunk.length, null);
+        if (!count)
+            break;
+        chunks.push(chunk.subarray(0, count));
+        size += count;
+    }
+    if (size > MAX_BYTES)
+        throw new Error();
+    return Buffer.concat(chunks, size).toString('utf8');
+}
+function validIds(value) {
+    return Array.isArray(value) && value.length <= 128 && value.every((item) => typeof item === 'string' && ID.test(item)) && new Set(value).size === value.length;
+}
+export function approvalContextMetadataIsSafe(value, effectiveUserId) {
+    if (!value.isFile() || value.nlink !== 1 || value.size > MAX_BYTES)
+        return false;
+    if (effectiveUserId === undefined)
+        return process.platform === 'win32';
+    return value.uid === effectiveUserId && (value.mode & 0o077) === 0;
+}
+export function loadApprovalContext(path = join(userInfo().homedir, '.config', 'holdyourvoice', 'approval-context.json')) {
+    let descriptor;
+    try {
+        descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const before = fstatSync(descriptor);
+        if (!approvalContextMetadataIsSafe(before, process.geteuid?.()))
+            throw new Error();
+        const value = JSON.parse(readBounded(descriptor));
+        const after = fstatSync(descriptor);
+        if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs
+            || !value || typeof value !== 'object' || !parseApprovalTrustStore(value.trustStore) || !value.authorizedSemanticEvaluatorIds
+            || !validIds(value.authorizedSemanticEvaluatorIds.normal) || !validIds(value.authorizedSemanticEvaluatorIds.highAssurance) || !validIds(value.authorizedHumanFinalizerIds))
+            throw new Error();
+        return { ...value, now: Math.floor(Date.now() / 1000) };
+    }
+    catch {
+        throw new Error('Approval context is unavailable or unsafe.');
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}

package/dist/approval-context.test.js

@@ -0,0 +1,38 @@
+import assert from 'node:assert/strict';
+import { chmodSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { approvalContextMetadataIsSafe, loadApprovalContext } from './approval-context.js';
+const context = { now: 0, trustStore: { version: '1', audience: '@holdyourvoice/hyv', maxCapabilityLifetimeSeconds: 300, keys: [] }, authorizedSemanticEvaluatorIds: { normal: ['reviewer-1'], highAssurance: [] }, authorizedHumanFinalizerIds: ['human-1'] };
+test('loads only a permission-checked installed approval context and replaces its clock', () => {
+    const root = mkdtempSync(join(tmpdir(), 'hyv-approval-context-'));
+    try {
+        const safe = join(root, 'safe.json');
+        writeFileSync(safe, JSON.stringify(context), { mode: 0o600 });
+        const loaded = loadApprovalContext(safe);
+        assert.deepEqual(loaded.authorizedSemanticEvaluatorIds.normal, ['reviewer-1']);
+        assert.notEqual(loaded.now, 0);
+        chmodSync(safe, 0o644);
+        assert.throws(() => loadApprovalContext(safe), /unavailable or unsafe/);
+        chmodSync(safe, 0o600);
+        const link = join(root, 'link.json');
+        symlinkSync(safe, link);
+        assert.throws(() => loadApprovalContext(link), /unavailable or unsafe/);
+        const malformed = join(root, 'malformed.json');
+        writeFileSync(malformed, JSON.stringify({ ...context, authorizedSemanticEvaluatorIds: { normal: ['bad id'], highAssurance: [] } }), { mode: 0o600 });
+        assert.throws(() => loadApprovalContext(malformed), /unavailable or unsafe/);
+        const malformedTrust = join(root, 'malformed-trust.json');
+        writeFileSync(malformedTrust, JSON.stringify({ ...context, trustStore: { ...context.trustStore, maxCapabilityLifetimeSeconds: 0 } }), { mode: 0o600 });
+        assert.throws(() => loadApprovalContext(malformedTrust), /unavailable or unsafe/);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test('fails closed when POSIX ownership metadata is unavailable on this host', () => {
+    const metadata = { isFile: () => true, nlink: 1, size: 10, uid: 501, mode: 0o600 };
+    assert.equal(approvalContextMetadataIsSafe(metadata, undefined), process.platform === 'win32');
+    assert.equal(approvalContextMetadataIsSafe(metadata, 501), true);
+    assert.equal(approvalContextMetadataIsSafe({ ...metadata, mode: 0o644 }, 501), false);
+});