From c7fe7e759f2fa93dabce6f49fa7c07cd5fe95067 Mon Sep 17 00:00:00 2001
From: Michael Heller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 29 Jul 2026 17:14:24 -0400
Subject: [PATCH 1/2] =?UTF-8?q?fix(pdf-viewer-demo):=20use=20assertEnabled?=
=?UTF-8?q?=20at=20the=20actual=20gate=20=E2=80=94=20deny()=20now=20bites?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Closes a register item: capability-ledger.deny() writes a blocked_by_policy
receipt into the ledger, but the sole production caller (the pdf-viewer
demo) used isEnabled() at the use-gate. isEnabled reports 'blocked_by_policy'
as false and drops silently — a policy refusal indistinguishable from a
not-yet-declared capability, which is the entire failure mode the register
item names.
- Inline CapabilityLedger drifted from the packaged version: it lacked
assertEnabled and let enable() take a null policyDecisionRef. Both fixed;
the packaged behaviour (enable requires a non-empty pdr, assertEnabled
throws on any non-enabled state naming the reason) is now mirrored.
- Click handlers use assertEnabled via a gatedClick wrapper; the diagnostic
surfaces in feature-output so the refusal is visible instead of dropped.
- Buttons stay clickable even when not enabled: the enforcement is at the
click site, and letting the click fire is what surfaces the diagnostic.
- Added pdf-export capability that is denied by policy, so the deny path
is now demonstrated end-to-end alongside pdf-sign (missing_plugin) and
pdf-viewer (enabled).
Package tests unchanged, 38/38 pass on origin/main head. This PR only
touches the demo — the surface most likely to drift because it's a manual
copy of the module.
---
apps/pdf-viewer-demo/index.html | 91 ++++++++++++++++++++++++++++++---
1 file changed, 83 insertions(+), 8 deletions(-)
diff --git a/apps/pdf-viewer-demo/index.html b/apps/pdf-viewer-demo/index.html
index f571740..a73af75 100644
--- a/apps/pdf-viewer-demo/index.html
+++ b/apps/pdf-viewer-demo/index.html
@@ -145,6 +145,10 @@
Feature Gate Demo
+
+
+
+
@@ -187,7 +191,17 @@
Feature Gate Demo
request(id, owner, opts = {}) { return this._emit(id, 'requested', owner, opts); }
negotiate(id, owner, opts = {}) { return this._emit(id, 'negotiating', owner, opts); }
setAvailable(id, owner, opts = {}) { return this._emit(id, 'available', owner, opts); }
- enable(id, owner, pdr = null, ev = []) { return this._emit(id, 'enabled', owner, { policyDecisionRef: pdr, evidenceRefs: ev }); }
+ // enable REQUIRES a policyDecisionRef — see packages/capability-ledger/src/index.js:
+ // 'enabled' is the only state that authorises use, so recording it without naming
+ // the decision that authorised it produces a grant indistinguishable from an
+ // adjudicated one. The inline copy previously accepted `pdr = null`, drifting from
+ // the packaged behaviour it exists to mirror.
+ enable(id, owner, pdr, ev = []) {
+ if (typeof pdr !== 'string' || pdr.trim() === '') {
+ throw new Error(`capability "${id}" cannot be enabled without a policyDecisionRef`);
+ }
+ return this._emit(id, 'enabled', owner, { policyDecisionRef: pdr, evidenceRefs: ev });
+ }
deny(id, owner, pdr = null, ev = []) { return this._emit(id, 'blocked_by_policy', owner, { policyDecisionRef: pdr, evidenceRefs: ev }); }
degrade(id, owner, ev = []) { return this._emit(id, 'degraded', owner, { evidenceRefs: ev }); }
setUnsupportedByRuntime(id, owner, ev = []) { return this._emit(id, 'unsupported_by_runtime', owner, { evidenceRefs: ev }); }
@@ -214,7 +228,27 @@
Feature Gate Demo
getState(id) { return this._receipts.get(id)?.state ?? null; }
getReceipt(id) { return this._receipts.get(id) ?? null; }
getAll() { return Array.from(this._receipts.values()); }
+
+ // isEnabled returns a value a caller may ignore; every caller that forgets it
+ // fails OPEN. Left in for UI-state readouts (button styling, gate label) where
+ // the boolean IS the answer being asked. For actual use-gates, prefer
+ // assertEnabled, which throws and cannot be silently ignored.
isEnabled(id) { return this.getState(id) === 'enabled'; }
+
+ // Fail-closed gate — parity with packages/capability-ledger/src/index.js.
+ // Distinguishes 'blocked_by_policy' (deny receipt exists) from 'not in ledger',
+ // so a refusal is diagnosable and cites its policyDecisionRef when there is one.
+ assertEnabled(id) {
+ const state = this.getState(id);
+ if (state === 'enabled') return this.getReceipt(id);
+ const receipt = this.getReceipt(id);
+ const because = receipt?.policyDecisionRef ? ` (policy decision: ${receipt.policyDecisionRef})` : '';
+ throw new Error(
+ state == null
+ ? `capability "${id}" is not in the ledger; refusing use of an undeclared capability`
+ : `capability "${id}" is "${state}", not "enabled"${because}; refusing use`,
+ );
+ }
}
// ── Bootstrap ledger with PDF viewer demo capabilities ────────────────
@@ -239,6 +273,16 @@
Feature Gate Demo
['plugin:ink-sign:not-installed'],
);
+ // pdf-export: denied by policy. Its click handler exercises the case the
+ // register item was open on: a deny() receipt exists, isEnabled reports false
+ // and drops silently, assertEnabled throws citing the policyDecisionRef.
+ ledger.declare('pdf-export', 'UI');
+ ledger.deny(
+ 'pdf-export', 'policy',
+ 'policy:deny-pdf-export:dlp-v2',
+ ['audit:dlp-review:2026-07'],
+ );
+
// live-collab: unsupported by server
ledger.declare('live-collab', 'UI');
ledger.setUnsupportedByServer(
@@ -305,7 +349,11 @@
Feature Gate Demo
const enabled = ledger.isEnabled(capabilityId);
const state = ledger.getState(capabilityId) ?? 'unknown';
- btn.disabled = !enabled;
+ // Buttons stay clickable even when the capability is not enabled: the
+ // enforcement is at the click site (assertEnabled), and letting the click
+ // fire is what surfaces the diagnostic — the point of closing the
+ // "deny records but blocks nothing" register item.
+ btn.disabled = false;
btn.className = enabled ? 'btn-ok' : 'btn-deny';
gate.textContent = enabled
? '✓ enabled'
@@ -313,19 +361,46 @@
Feature Gate Demo
gate.style.color = enabled ? 'var(--color-enabled)' : 'var(--color-blocked)';
}
- updateGate('pdf-viewer', 'btn-pdf-view', 'gate-pdf-view');
- updateGate('pdf-sign', 'btn-pdf-sign', 'gate-pdf-sign');
+ updateGate('pdf-viewer', 'btn-pdf-view', 'gate-pdf-view');
+ updateGate('pdf-sign', 'btn-pdf-sign', 'gate-pdf-sign');
+ updateGate('pdf-export', 'btn-pdf-export', 'gate-pdf-export');
const output = document.getElementById('feature-output');
+ // Use assertEnabled at the actual use-gate: an isEnabled check a caller can ignore
+ // is the same defect as no check. ledger.deny(...) records a 'blocked_by_policy'
+ // receipt, which isEnabled reports as false and drops silently — a policy refusal
+ // indistinguishable from a not-yet-declared capability. assertEnabled distinguishes
+ // them and cites the policyDecisionRef when there is one.
+ function gatedClick(capabilityId, onGranted) {
+ try {
+ ledger.assertEnabled(capabilityId);
+ onGranted();
+ } catch (err) {
+ output.textContent = `⛔ ${err.message}`;
+ output.style.color = 'var(--color-blocked)';
+ }
+ }
+
document.getElementById('btn-pdf-view').addEventListener('click', () => {
- if (!ledger.isEnabled('pdf-viewer')) return;
- output.textContent = '📄 PDF viewer opened (capability confirmed enabled by ledger).';
+ gatedClick('pdf-viewer', () => {
+ output.textContent = '📄 PDF viewer opened (capability confirmed enabled by ledger).';
+ output.style.color = '';
+ });
});
document.getElementById('btn-pdf-sign').addEventListener('click', () => {
- if (!ledger.isEnabled('pdf-sign')) return;
- output.textContent = '✍ PDF signed.';
+ gatedClick('pdf-sign', () => {
+ output.textContent = '✍ PDF signed.';
+ output.style.color = '';
+ });
+ });
+
+ document.getElementById('btn-pdf-export').addEventListener('click', () => {
+ gatedClick('pdf-export', () => {
+ output.textContent = '📤 PDF exported.';
+ output.style.color = '';
+ });
});
From 78c702b914449196ce3c54824325727d9a776da3 Mon Sep 17 00:00:00 2001
From: Michael Heller