@flashyid/sdk 0.1.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,194 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.REVOCATION_SIGNER_PREFIXES = exports.REVOCATION_REASON_MIN = exports.REVOCATION_LIST_VERSION = void 0;
4
+ exports.emptyRevocationList = emptyRevocationList;
5
+ exports.isAccountableSigner = isAccountableSigner;
6
+ exports.revoke = revoke;
7
+ exports.revokedAsOf = revokedAsOf;
8
+ exports.revocationOf = revocationOf;
9
+ exports.extendsList = extendsList;
10
+ exports.validateRevocationList = validateRevocationList;
11
+ exports.verifyChainAgainst = verifyChainAgainst;
12
+ const grants_js_1 = require("./grants.js");
13
+ /**
14
+ * The revocation list — `revocation/1`.
15
+ *
16
+ * `verifyChain` has always taken a `revokedJtis` set and walked revocation
17
+ * down the chain (invariant 3). What it never had was the record that set comes
18
+ * FROM: a relying party was expected to already know what had been revoked,
19
+ * "which is the one thing it cannot know about another organization" (source
20
+ * audit, finding "No revocation pointer on the link"). This is that record.
21
+ *
22
+ * Shape, and the rules that hold it:
23
+ * - It is APPEND-ONLY. Every entry carries a `seq` one past the entry before
24
+ * it, and `head` is the latest. A list is never edited: a mistaken
25
+ * revocation is corrected by issuing a new grant, never by removing the
26
+ * entry, because a reader that fetched revision 5 must find revision 5
27
+ * intact inside revision 7 (`extendsList`).
28
+ * - Every entry is SIGNED BY A PERSON OR AN ORGANISATION — `by` is a
29
+ * `person/` or `org/` id, never `agent/`. A revocation is a correction to
30
+ * the record, and the estate's posture for corrections is that somebody who
31
+ * can be asked why signs it. A reason of at least 24 characters is refused
32
+ * otherwise, for the same reason: "rotated" tells the next reader nothing.
33
+ * - It is DETERMINISTIC. No clock: the time of a revocation is an argument
34
+ * (`atSec`), and entries do not go backwards in time.
35
+ * - A verdict names the REVISION it was computed against (`asOf`), so a
36
+ * relying party can say "revoked as of revision 7" and an auditor can
37
+ * recompute it with the same revision rather than today's.
38
+ *
39
+ * Nothing here signs the list as a document; that is `signRevocationList` /
40
+ * `verifyRevocationList` in `src/sdk/revocation.ts`, which use the same EdDSA
41
+ * key and JWKS the assertions do. This module is pure and dependency-free, like
42
+ * the rest of the kernel.
43
+ */
44
+ exports.REVOCATION_LIST_VERSION = 'revocation/1';
45
+ /** The shortest reason the list accepts. The estate's bound for a correction. */
46
+ exports.REVOCATION_REASON_MIN = 24;
47
+ /** The signer prefixes a revocation may carry. An `agent/` cannot withdraw authority. */
48
+ exports.REVOCATION_SIGNER_PREFIXES = ['person/', 'org/'];
49
+ function refuse(code, detail) {
50
+ return { ok: false, code, detail };
51
+ }
52
+ /** Revision 0: nothing revoked. */
53
+ function emptyRevocationList(issuer) {
54
+ return { v: exports.REVOCATION_LIST_VERSION, issuer, head: 0, entries: [] };
55
+ }
56
+ /** Is this an id the estate lets sign a correction? */
57
+ function isAccountableSigner(by) {
58
+ return typeof by === 'string' && exports.REVOCATION_SIGNER_PREFIXES.some((p) => by.startsWith(p) && by.length > p.length);
59
+ }
60
+ /**
61
+ * Append a revocation. Returns a NEW list one revision ahead, or a refusal; the
62
+ * input list is never mutated. Refuses by name rather than clamping, so a
63
+ * caller that passes a short reason or an agent signer learns which rule it
64
+ * broke rather than finding its revocation quietly absent.
65
+ */
66
+ function revoke(list, input) {
67
+ if (typeof input.jti !== 'string' || input.jti.length === 0)
68
+ return refuse('malformed_id', 'jti must be a non-empty string');
69
+ if (!isAccountableSigner(input.by)) {
70
+ return refuse('unaccountable_signer', `a revocation is signed by a person/ or org/ id, not ${JSON.stringify(input.by)}`);
71
+ }
72
+ const reason = typeof input.reason === 'string' ? input.reason.trim() : '';
73
+ if (reason.length < exports.REVOCATION_REASON_MIN) {
74
+ return refuse('reason_too_short', `reason must be at least ${exports.REVOCATION_REASON_MIN} characters (got ${reason.length})`);
75
+ }
76
+ if (!Number.isFinite(input.atSec))
77
+ return refuse('out_of_order', 'atSec must be a finite number of seconds');
78
+ const last = list.entries[list.entries.length - 1];
79
+ if (last && input.atSec < last.at) {
80
+ return refuse('out_of_order', `entry dated ${input.atSec} precedes the previous entry at ${last.at}; the list only moves forward`);
81
+ }
82
+ if (list.entries.some((e) => e.jti === input.jti))
83
+ return refuse('already_revoked', `${input.jti} is already revoked`);
84
+ const entry = { seq: list.head + 1, jti: input.jti, by: input.by, reason, at: input.atSec };
85
+ return { v: exports.REVOCATION_LIST_VERSION, issuer: list.issuer, head: list.head + 1, entries: [...list.entries, entry] };
86
+ }
87
+ /**
88
+ * The revoked ids as of a revision. `asOf` defaults to the head; a revision the
89
+ * list does not hold (negative, non-integer, or past the head) THROWS, because
90
+ * "as of revision 9" computed from a list that ends at 7 is a claim nothing
91
+ * computed — the same reason a derived field is never accepted as input.
92
+ */
93
+ function revokedAsOf(list, asOf = list.head) {
94
+ if (!Number.isInteger(asOf) || asOf < 0 || asOf > list.head) {
95
+ throw new RangeError(`revocation list ${list.issuer} holds revisions 0..${list.head}; asOf ${asOf} is not one of them`);
96
+ }
97
+ const out = new Set();
98
+ for (const e of list.entries)
99
+ if (e.seq <= asOf)
100
+ out.add(e.jti);
101
+ return out;
102
+ }
103
+ /** The entry that revoked `jti` at or before `asOf`, if any. */
104
+ function revocationOf(list, jti, asOf = list.head) {
105
+ return list.entries.find((e) => e.jti === jti && e.seq <= asOf);
106
+ }
107
+ /**
108
+ * Is `next` the same list, later? A reader that cached revision n refuses a
109
+ * document that claims to be a later revision but rewrote anything in 1..n:
110
+ * same issuer, head not lower, and every entry it already held byte-for-byte
111
+ * where it was. This is the append-only rule from the reader's side.
112
+ */
113
+ function extendsList(previous, next) {
114
+ if (previous.issuer !== next.issuer)
115
+ return false;
116
+ if (next.head < previous.head)
117
+ return false;
118
+ for (let i = 0; i < previous.entries.length; i++) {
119
+ if (!sameEntry(previous.entries[i], next.entries[i]))
120
+ return false;
121
+ }
122
+ return true;
123
+ }
124
+ function sameEntry(a, b) {
125
+ return a !== undefined && b !== undefined && a.seq === b.seq && a.jti === b.jti && a.by === b.by && a.reason === b.reason && a.at === b.at;
126
+ }
127
+ /**
128
+ * Is this a well-formed revocation/1 list? Every rule `revoke` enforces on the
129
+ * way in is enforced again here on the way out of the wire, so a caller that
130
+ * assembles a list by hand and never calls `revoke` still cannot hand a
131
+ * verifier a short reason, an agent signer, a gap in the sequence, or a clock
132
+ * that runs backwards. Returns the typed list, or a refusal naming the entry.
133
+ */
134
+ function validateRevocationList(v) {
135
+ if (typeof v !== 'object' || v === null || Array.isArray(v))
136
+ return refuse('malformed_list', 'not an object');
137
+ const l = v;
138
+ if (l.v !== exports.REVOCATION_LIST_VERSION)
139
+ return refuse('malformed_list', `v must be ${exports.REVOCATION_LIST_VERSION}`);
140
+ if (typeof l.issuer !== 'string' || l.issuer.length === 0)
141
+ return refuse('malformed_list', 'issuer must be a non-empty string');
142
+ if (!Array.isArray(l.entries))
143
+ return refuse('malformed_list', 'entries must be an array');
144
+ if (l.head !== l.entries.length)
145
+ return refuse('malformed_list', `head ${String(l.head)} is not the entry count ${l.entries.length}`);
146
+ let rebuilt = emptyRevocationList(l.issuer);
147
+ for (let i = 0; i < l.entries.length; i++) {
148
+ const e = l.entries[i];
149
+ if (typeof e !== 'object' || e === null)
150
+ return refuse('malformed_list', `entry ${i} is not an object`);
151
+ const r = e;
152
+ if (r.seq !== i + 1)
153
+ return refuse('malformed_list', `entry ${i} has seq ${String(r.seq)}, expected ${i + 1}`);
154
+ if (typeof r.reason !== 'string' || typeof r.by !== 'string' || typeof r.jti !== 'string' || typeof r.at !== 'number') {
155
+ return refuse('malformed_list', `entry ${i} is missing a field`);
156
+ }
157
+ if (r.reason !== r.reason.trim())
158
+ return refuse('malformed_list', `entry ${i} reason carries surrounding whitespace`);
159
+ const next = revoke(rebuilt, { jti: r.jti, by: r.by, reason: r.reason, atSec: r.at });
160
+ if ('ok' in next)
161
+ return { ...next, detail: `entry ${i}: ${next.detail ?? next.code}` };
162
+ rebuilt = next;
163
+ }
164
+ return rebuilt;
165
+ }
166
+ /**
167
+ * `verifyChain` against a revocation list at a revision. The result is the
168
+ * kernel's — a revoked link, or any ancestor, refuses `revoked` at the highest
169
+ * revoked index, and everything beneath it is dead with it — plus the revision
170
+ * it was computed against, so the verdict can be restated and recomputed. A
171
+ * `revoked` refusal's detail names the entry: which link, who withdrew it, why.
172
+ *
173
+ * `extraRevoked` lets a relying party fold in ids it knows about from
174
+ * elsewhere (its own local withdrawals); they are unioned, never substituted.
175
+ */
176
+ function verifyChainAgainst(chain, nowSec, list, opts = {}) {
177
+ const asOf = opts.asOf ?? list.head;
178
+ const revoked = new Set(revokedAsOf(list, asOf));
179
+ for (const jti of opts.extraRevoked ?? [])
180
+ revoked.add(jti);
181
+ const result = (0, grants_js_1.verifyChain)(chain, nowSec, revoked);
182
+ if (!result.ok && result.code === 'revoked' && result.at !== undefined) {
183
+ const link = chain[result.at];
184
+ const entry = link ? revocationOf(list, link.jti, asOf) : undefined;
185
+ if (entry) {
186
+ return {
187
+ result: { ...result, detail: `link ${entry.jti} revoked by ${entry.by} at revision ${entry.seq}: ${entry.reason}` },
188
+ asOf,
189
+ issuer: list.issuer,
190
+ };
191
+ }
192
+ }
193
+ return { result, asOf, issuer: list.issuer };
194
+ }
package/dist/cjs/index.js CHANGED
@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
14
  for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
15
  };
16
16
  Object.defineProperty(exports, "__esModule", { value: true });
17
- exports.trustedRootsFromCharters = exports.summarizeGrants = exports.grantsFromCharter = exports.AGENT_SUBJECT = exports.toDirectoryId = exports.fromDirectoryId = exports.isAgentSubject = exports.parseAgentSubject = exports.agentSubject = exports.grantAdapter = exports.recordOnly = exports.withTimeout = exports.enforce = exports.evaluateGrant = void 0;
17
+ exports.trustedRootsFromCharters = exports.summarizeGrants = exports.grantsFromCharter = exports.railGrantFromChain = exports.mintGrantToken = exports.mintConsentToken = exports.mintIssuerToken = exports.AGENT_SUBJECT = exports.toDirectoryId = exports.fromDirectoryId = exports.isAgentSubject = exports.parseAgentSubject = exports.agentSubject = exports.grantAdapter = exports.recordOnly = exports.withTimeout = exports.enforce = exports.evaluateGrant = void 0;
18
18
  /**
19
19
  * @flashyid/sdk — the relying-party surface for Flashy ID delegated authority.
20
20
  *
@@ -43,6 +43,14 @@ Object.defineProperty(exports, "isAgentSubject", { enumerable: true, get: functi
43
43
  Object.defineProperty(exports, "fromDirectoryId", { enumerable: true, get: function () { return subject_js_1.fromDirectoryId; } });
44
44
  Object.defineProperty(exports, "toDirectoryId", { enumerable: true, get: function () { return subject_js_1.toDirectoryId; } });
45
45
  Object.defineProperty(exports, "AGENT_SUBJECT", { enumerable: true, get: function () { return subject_js_1.AGENT_SUBJECT; } });
46
+ // Rail tokens — flashyID minting the three tokens Flashy Rails verifies
47
+ // (issuer / consent / grant). The complement of the rail's FlashyIdVerifier;
48
+ // `railGrantFromChain` bridges the delegation kernel to the rail's flat grant.
49
+ var tokens_js_1 = require("./rail/tokens.js");
50
+ Object.defineProperty(exports, "mintIssuerToken", { enumerable: true, get: function () { return tokens_js_1.mintIssuerToken; } });
51
+ Object.defineProperty(exports, "mintConsentToken", { enumerable: true, get: function () { return tokens_js_1.mintConsentToken; } });
52
+ Object.defineProperty(exports, "mintGrantToken", { enumerable: true, get: function () { return tokens_js_1.mintGrantToken; } });
53
+ Object.defineProperty(exports, "railGrantFromChain", { enumerable: true, get: function () { return tokens_js_1.railGrantFromChain; } });
46
54
  var charterGrants_js_1 = require("./init/charterGrants.js");
47
55
  Object.defineProperty(exports, "grantsFromCharter", { enumerable: true, get: function () { return charterGrants_js_1.grantsFromCharter; } });
48
56
  Object.defineProperty(exports, "summarizeGrants", { enumerable: true, get: function () { return charterGrants_js_1.summarizeGrants; } });
@@ -0,0 +1,136 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.mintIssuerToken = mintIssuerToken;
4
+ exports.mintConsentToken = mintConsentToken;
5
+ exports.mintGrantToken = mintGrantToken;
6
+ exports.railGrantFromChain = railGrantFromChain;
7
+ const sign_js_1 = require("../sdk/sign.js");
8
+ const grants_js_1 = require("../grants/grants.js");
9
+ /** Mint a `rewards:issue`-scoped bearer token for the earn path. */
10
+ function mintIssuerToken(signer, input) {
11
+ return (0, sign_js_1.signAssertion)({
12
+ privateKey: signer.privateKey,
13
+ issuer: signer.issuer,
14
+ audience: signer.audience,
15
+ subject: input.subject,
16
+ kid: signer.kid,
17
+ iatSec: signer.iatSec,
18
+ expiresInSec: input.expiresInSec ?? 300,
19
+ jti: input.jti,
20
+ extraClaims: { scope: input.scope ?? ['rewards:issue'] },
21
+ });
22
+ }
23
+ /** Mint a consent token bound to one draft and holder. */
24
+ function mintConsentToken(signer, input) {
25
+ return (0, sign_js_1.signAssertion)({
26
+ privateKey: signer.privateKey,
27
+ issuer: signer.issuer,
28
+ audience: signer.audience,
29
+ subject: input.holderId,
30
+ kid: signer.kid,
31
+ iatSec: signer.iatSec,
32
+ expiresInSec: input.expiresInSec ?? 120,
33
+ jti: input.jti,
34
+ extraClaims: {
35
+ typ: 'consent',
36
+ draftId: input.draftId,
37
+ holderId: input.holderId,
38
+ action: input.action,
39
+ approvedAt: (input.approvedAt ?? new Date()).toISOString(),
40
+ },
41
+ });
42
+ }
43
+ /** Mint a grant token in the rail's flat grant vocabulary. */
44
+ function mintGrantToken(signer, input) {
45
+ return (0, sign_js_1.signAssertion)({
46
+ privateKey: signer.privateKey,
47
+ issuer: signer.issuer,
48
+ audience: signer.audience,
49
+ subject: input.holderId,
50
+ kid: signer.kid,
51
+ iatSec: signer.iatSec,
52
+ expiresInSec: input.expiresInSec ?? 300,
53
+ jti: input.grantId,
54
+ extraClaims: {
55
+ typ: 'grant',
56
+ grantId: input.grantId,
57
+ holderId: input.holderId,
58
+ spenderId: input.spenderId,
59
+ assetId: input.assetId,
60
+ capMinor: input.capMinor,
61
+ remainingMinor: input.remainingMinor ?? input.capMinor,
62
+ purpose: input.purpose,
63
+ ...(input.expiresAt ? { expiresAt: input.expiresAt.toISOString() } : {}),
64
+ revoked: input.revoked ?? false,
65
+ parentGrantId: input.parentGrantId ?? null,
66
+ },
67
+ });
68
+ }
69
+ /**
70
+ * Project a flashyID delegation CHAIN onto the rail's flat grant params — the
71
+ * bridge between flashyID's grant vocabulary (a chain of scp/res/lim links) and
72
+ * the rail's (a flat, capped grant).
73
+ *
74
+ * flashyID's chain is the source of truth for delegation: `verifyChain` folds
75
+ * it to an effective grant (tightest limit, earliest expiry, the leaf holder,
76
+ * the accountable root). This maps that onto what the rail draws down:
77
+ *
78
+ * holderId ← the accountable root (whose authority backs the spend)
79
+ * spenderId ← the leaf holder (the agent actually spending)
80
+ * capMinor ← the effective spend_max (the chain's tightest ceiling)
81
+ * expiresAt ← the effective expiry (the earliest across the chain)
82
+ *
83
+ * THE MAPPING IS A DECISION, NOT A DERIVATION, and it is the one thing on this
84
+ * whole path that wants ratification: it treats the chain root as the value
85
+ * holder and the leaf as the spender, which is right when a person/org delegates
86
+ * spend of their own Gold down to an agent. If the estate wants a different
87
+ * correspondence, this function is the single place it lives. Throws if the
88
+ * chain is unsound, if it carries no spend ceiling (an uncapped grant must not
89
+ * become an uncapped rail draw), if `scope` is required and absent, or if the
90
+ * chain's root is not one `extra.trustedRoots` names.
91
+ *
92
+ * `trustedRoots` IS REQUIRED, not optional, and that is deliberate: this is the
93
+ * root-trust-policy decision docs/rail-grant.md named as the one thing left
94
+ * before this path could take a real caller, and the decided answer (estate-
95
+ * named roots only — the `person/`/`org/` ids an AAO charter actually
96
+ * accounts to, via `trustedRootsFromCharters`; see charterGrants.ts) is a
97
+ * closed allow-list, never "any sound chain". A sound chain proves only that it
98
+ * narrows correctly and is held by whoever it says — `verifyChain` — never that
99
+ * its root is one the estate is willing to vouch spend for. Letting a caller
100
+ * omit the check (as this function did until it was wired here) would reopen
101
+ * exactly the fail-open gap `enforce()`'s 0.2.0 fix closed on the other primitive
102
+ * in this package: a boundary with no way to pass a trust set is a boundary a
103
+ * caller can walk around by never building one. There is deliberately no
104
+ * "trust everyone" sentinel; a caller that genuinely wants that passes its own
105
+ * unbounded set, in its own code, rather than getting it by omission.
106
+ */
107
+ async function railGrantFromChain(signer, chain, extra) {
108
+ const nowSec = extra.nowSec ?? Math.floor(Date.now() / 1000);
109
+ const effective = (0, grants_js_1.verifyChain)(chain, nowSec, new Set());
110
+ if (!effective.ok) {
111
+ throw new Error(`railGrantFromChain: unsound delegation chain (${effective.code})`);
112
+ }
113
+ const rooted = (0, grants_js_1.rootsWithin)(effective, extra.trustedRoots);
114
+ if (rooted !== true) {
115
+ throw new Error(`railGrantFromChain: ${rooted.code}${rooted.detail ? ` (${rooted.detail})` : ''}`);
116
+ }
117
+ if (extra.requireScope && !effective.scp.includes(extra.requireScope)) {
118
+ throw new Error(`railGrantFromChain: chain does not grant the required scope "${extra.requireScope}"`);
119
+ }
120
+ if (typeof effective.lim.spend_max !== 'number') {
121
+ throw new Error('railGrantFromChain: chain has no spend ceiling; an uncapped grant must not become an uncapped rail draw');
122
+ }
123
+ const capMinor = effective.lim.spend_max;
124
+ return mintGrantToken(signer, {
125
+ grantId: extra.grantId,
126
+ holderId: effective.root,
127
+ spenderId: effective.holder,
128
+ assetId: extra.assetId,
129
+ capMinor,
130
+ remainingMinor: capMinor,
131
+ purpose: extra.purpose,
132
+ expiresAt: new Date(effective.exp * 1000),
133
+ parentGrantId: chain.length > 1 ? chain[chain.length - 2].jti : null,
134
+ expiresInSec: extra.expiresInSec,
135
+ });
136
+ }
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.IMPACT_ORDER = exports.impactRank = exports.grantFromCharterRole = exports.rootsWithin = exports.permits = exports.verifyChain = exports.attenuate = exports.issueRoot = exports.signAssertion = exports.authorize = exports.verifyAssertion = void 0;
3
+ exports.REVOCATION_SIGNER_PREFIXES = exports.REVOCATION_REASON_MIN = exports.REVOCATION_LIST_VERSION = exports.isAccountableSigner = exports.verifyChainAgainst = exports.validateRevocationList = exports.extendsList = exports.revocationOf = exports.revokedAsOf = exports.revoke = exports.emptyRevocationList = exports.IMPACT_ORDER = exports.impactRank = exports.grantFromCharterRole = exports.rootsWithin = exports.permits = exports.verifyChain = exports.attenuate = exports.issueRoot = exports.verifyRevocationList = exports.signRevocationList = exports.signAssertion = exports.authorize = exports.verifyAssertion = void 0;
4
4
  /**
5
5
  * @flashyid/sdk — verify a Flashy ID assertion and the delegation it carries.
6
6
  *
@@ -16,6 +16,9 @@ Object.defineProperty(exports, "verifyAssertion", { enumerable: true, get: funct
16
16
  Object.defineProperty(exports, "authorize", { enumerable: true, get: function () { return verify_js_1.authorize; } });
17
17
  var sign_js_1 = require("./sign.js");
18
18
  Object.defineProperty(exports, "signAssertion", { enumerable: true, get: function () { return sign_js_1.signAssertion; } });
19
+ var revocation_js_1 = require("./revocation.js");
20
+ Object.defineProperty(exports, "signRevocationList", { enumerable: true, get: function () { return revocation_js_1.signRevocationList; } });
21
+ Object.defineProperty(exports, "verifyRevocationList", { enumerable: true, get: function () { return revocation_js_1.verifyRevocationList; } });
19
22
  var index_js_1 = require("../grants/index.js");
20
23
  Object.defineProperty(exports, "issueRoot", { enumerable: true, get: function () { return index_js_1.issueRoot; } });
21
24
  Object.defineProperty(exports, "attenuate", { enumerable: true, get: function () { return index_js_1.attenuate; } });
@@ -25,3 +28,14 @@ Object.defineProperty(exports, "rootsWithin", { enumerable: true, get: function
25
28
  Object.defineProperty(exports, "grantFromCharterRole", { enumerable: true, get: function () { return index_js_1.grantFromCharterRole; } });
26
29
  Object.defineProperty(exports, "impactRank", { enumerable: true, get: function () { return index_js_1.impactRank; } });
27
30
  Object.defineProperty(exports, "IMPACT_ORDER", { enumerable: true, get: function () { return index_js_1.IMPACT_ORDER; } });
31
+ Object.defineProperty(exports, "emptyRevocationList", { enumerable: true, get: function () { return index_js_1.emptyRevocationList; } });
32
+ Object.defineProperty(exports, "revoke", { enumerable: true, get: function () { return index_js_1.revoke; } });
33
+ Object.defineProperty(exports, "revokedAsOf", { enumerable: true, get: function () { return index_js_1.revokedAsOf; } });
34
+ Object.defineProperty(exports, "revocationOf", { enumerable: true, get: function () { return index_js_1.revocationOf; } });
35
+ Object.defineProperty(exports, "extendsList", { enumerable: true, get: function () { return index_js_1.extendsList; } });
36
+ Object.defineProperty(exports, "validateRevocationList", { enumerable: true, get: function () { return index_js_1.validateRevocationList; } });
37
+ Object.defineProperty(exports, "verifyChainAgainst", { enumerable: true, get: function () { return index_js_1.verifyChainAgainst; } });
38
+ Object.defineProperty(exports, "isAccountableSigner", { enumerable: true, get: function () { return index_js_1.isAccountableSigner; } });
39
+ Object.defineProperty(exports, "REVOCATION_LIST_VERSION", { enumerable: true, get: function () { return index_js_1.REVOCATION_LIST_VERSION; } });
40
+ Object.defineProperty(exports, "REVOCATION_REASON_MIN", { enumerable: true, get: function () { return index_js_1.REVOCATION_REASON_MIN; } });
41
+ Object.defineProperty(exports, "REVOCATION_SIGNER_PREFIXES", { enumerable: true, get: function () { return index_js_1.REVOCATION_SIGNER_PREFIXES; } });
@@ -0,0 +1,84 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.signRevocationList = signRevocationList;
37
+ exports.verifyRevocationList = verifyRevocationList;
38
+ const jose_1 = require("jose");
39
+ const revocation_js_1 = require("../grants/revocation.js");
40
+ /**
41
+ * Sign a revocation list as a compact JWS. Throws on a list that does not
42
+ * validate — an issuer must never put its key on a malformed record.
43
+ */
44
+ async function signRevocationList(list, input) {
45
+ const checked = (0, revocation_js_1.validateRevocationList)(list);
46
+ if ('ok' in checked)
47
+ throw new Error(`signRevocationList: refusing to sign a malformed list (${checked.code}: ${checked.detail ?? ''})`);
48
+ if (!Number.isInteger(input.iatSec))
49
+ throw new Error('signRevocationList: iatSec must be an integer number of seconds');
50
+ return new jose_1.SignJWT({ typ: revocation_js_1.REVOCATION_LIST_VERSION, v: checked.v, head: checked.head, entries: checked.entries })
51
+ .setProtectedHeader({ alg: 'EdDSA', ...(input.kid ? { kid: input.kid } : {}) })
52
+ .setIssuer(checked.issuer)
53
+ .setIssuedAt(input.iatSec)
54
+ .sign(input.privateKey);
55
+ }
56
+ /**
57
+ * Verify a signed revocation list: signature against the issuer's JWKS, `iss`,
58
+ * then every structural rule of `revocation/1` (contiguous revisions,
59
+ * accountable signers, reasons of length, time never running backwards).
60
+ * Returns `null` on any failure — a list that does not verify is no list, and
61
+ * a relying party holding none should go on using the revision it last
62
+ * verified rather than an empty set (unread is not zero).
63
+ */
64
+ async function verifyRevocationList(jws, opts) {
65
+ if (!jws)
66
+ return null;
67
+ const key = opts.getKey ?? (await remoteKey(opts.issuer));
68
+ try {
69
+ const { payload } = await (0, jose_1.jwtVerify)(jws, key, { issuer: opts.issuer, algorithms: ['EdDSA'] });
70
+ if (payload.typ !== revocation_js_1.REVOCATION_LIST_VERSION || typeof payload.iat !== 'number')
71
+ return null;
72
+ const list = (0, revocation_js_1.validateRevocationList)({ v: payload.v, issuer: payload.iss, head: payload.head, entries: payload.entries });
73
+ if ('ok' in list)
74
+ return null;
75
+ return { list, signedAt: payload.iat };
76
+ }
77
+ catch {
78
+ return null;
79
+ }
80
+ }
81
+ async function remoteKey(issuer) {
82
+ const { createRemoteJWKSet } = await Promise.resolve().then(() => __importStar(require('jose')));
83
+ return createRemoteJWKSet(new URL(`${issuer.replace(/\/+$/, '')}/.well-known/jwks.json`));
84
+ }
@@ -4,6 +4,7 @@ exports.verifyAssertion = verifyAssertion;
4
4
  exports.authorize = authorize;
5
5
  const jose_1 = require("jose");
6
6
  const grants_js_1 = require("../grants/grants.js");
7
+ const revocation_js_1 = require("../grants/revocation.js");
7
8
  const types_js_1 = require("../grants/types.js");
8
9
  function isStringArray(v) {
9
10
  return Array.isArray(v) && v.every((x) => typeof x === 'string');
@@ -30,7 +31,9 @@ function isGrantLink(v) {
30
31
  isLimit(l.lim) &&
31
32
  typeof l.iat === 'number' &&
32
33
  typeof l.exp === 'number' &&
33
- typeof l.jti === 'string');
34
+ (l.nbf === undefined || typeof l.nbf === 'number') &&
35
+ typeof l.jti === 'string' &&
36
+ (typeof l.par === 'string' || l.par === null));
34
37
  }
35
38
  /**
36
39
  * A `del` claim is attacker-adjacent wire data: it arrives inside a signed
@@ -112,12 +115,22 @@ async function authorize(token, demand, opts) {
112
115
  }
113
116
  return { assertion, result: { ok: false, code: 'empty_chain', detail: 'assertion carries no delegation' } };
114
117
  }
115
- const verified = (0, grants_js_1.verifyChain)(assertion.del, opts.nowSec, opts.revokedJtis ?? new Set());
118
+ let verified;
119
+ const stamp = {};
120
+ if (opts.revocations) {
121
+ const verdict = (0, revocation_js_1.verifyChainAgainst)(assertion.del, opts.nowSec, opts.revocations, { asOf: opts.asOf, extraRevoked: opts.revokedJtis });
122
+ verified = verdict.result;
123
+ stamp.revocationsAsOf = verdict.asOf;
124
+ }
125
+ else {
126
+ verified = (0, grants_js_1.verifyChain)(assertion.del, opts.nowSec, opts.revokedJtis ?? new Set());
127
+ }
116
128
  if (!verified.ok)
117
- return { assertion, result: verified };
129
+ return { assertion, result: verified, ...stamp };
118
130
  if (verified.holder !== assertion.sub) {
119
131
  return {
120
132
  assertion,
133
+ ...stamp,
121
134
  result: {
122
135
  ok: false,
123
136
  code: 'broken_chain',
@@ -131,8 +144,8 @@ async function authorize(token, demand, opts) {
131
144
  if (opts.trustedRoots !== undefined) {
132
145
  const rooted = (0, grants_js_1.rootsWithin)(verified, opts.trustedRoots);
133
146
  if (rooted !== true)
134
- return { assertion, result: rooted };
147
+ return { assertion, result: rooted, ...stamp };
135
148
  }
136
149
  const p = (0, grants_js_1.permits)(verified, demand);
137
- return { assertion, result: p === true ? verified : p };
150
+ return { assertion, result: p === true ? verified : p, ...stamp };
138
151
  }
@@ -1,4 +1,5 @@
1
1
  import { type Demand } from '../grants/index.js';
2
+ import { type RevocationList } from '../grants/revocation.js';
2
3
  import { type GrantChain, type Impact, type RefusalCode } from '../grants/types.js';
3
4
  /**
4
5
  * The enforcement gate.
@@ -29,12 +30,26 @@ export interface EnforcementResult {
29
30
  code?: RefusalCode;
30
31
  /** For ESCALATE, the impact bar at or above which a human must co-sign. */
31
32
  escalateAtOrAbove?: Impact;
33
+ /**
34
+ * When a `revocations` list was supplied: the revision of it this verdict
35
+ * was computed against, so "ALLOW as of revision 7" can be restated and an
36
+ * auditor can recompute it against the same revision rather than today's.
37
+ */
38
+ revocationsAsOf?: number;
32
39
  }
33
40
  export interface EvaluateOptions {
34
41
  /** Seconds since epoch to evaluate expiry against. */
35
42
  nowSec: number;
36
43
  /** Revoked grant ids — a revoked link, or any ancestor, kills the chain. */
37
44
  revokedJtis?: ReadonlySet<string>;
45
+ /**
46
+ * The issuer's `revocation/1` list (verified with `verifyRevocationList`, or
47
+ * built locally). Unioned with `revokedJtis`, never substituted for it, and
48
+ * the verdict carries the revision it was computed against.
49
+ */
50
+ revocations?: RevocationList;
51
+ /** The revision of `revocations` to evaluate at; defaults to its head. */
52
+ asOf?: number;
38
53
  }
39
54
  /**
40
55
  * The gate decision for a signed grant chain against a demanded action. Pure.
@@ -61,6 +76,8 @@ export interface DecisionInput {
61
76
  demand: Demand;
62
77
  nowSec: number;
63
78
  revokedJtis?: ReadonlySet<string>;
79
+ revocations?: RevocationList;
80
+ asOf?: number;
64
81
  }
65
82
  /**
66
83
  * The default: record only, never block. An org with no adapter configured, or
@@ -71,17 +88,32 @@ export declare const recordOnly: EnforcementAdapter;
71
88
  /** An adapter backed by the grant kernel — the real gate. */
72
89
  export declare function grantAdapter(): EnforcementAdapter;
73
90
  export interface EnforceOptions {
74
- /** Milliseconds to wait for the adapter before falling back. Default 5000. */
91
+ /** Milliseconds to wait for the adapter before giving up on it. Default 5000. */
75
92
  timeoutMs?: number;
76
- /** Raised when the adapter is unreachable and the gate falls back to allow —
77
- * the CRITICAL alert an operator wires to their monitoring. */
93
+ /** Raised when the adapter is unreachable or times out — the CRITICAL alert
94
+ * an operator wires to their monitoring, whatever `unavailable` then does. */
78
95
  onUnavailable?: (error: unknown) => void;
96
+ /**
97
+ * What the gate answers when the adapter cannot: `'deny'` (the default) fails
98
+ * closed, `'escalate'` hands the decision to a human, `'allow'` records and
99
+ * proceeds. An org that registered an adapter asked for enforcement, and an
100
+ * enforcement that answers ALLOW the moment its policy service is down is a
101
+ * boundary an attacker clears by unplugging it (external audit, 2026-10-10).
102
+ * `'allow'` is still available for the record-only deployments the mesh was
103
+ * first built for; it is now a choice written in the caller's code.
104
+ */
105
+ unavailable?: 'deny' | 'escalate' | 'allow';
79
106
  }
80
107
  /**
81
108
  * Run a decision through an adapter with the operational contract: await the
82
- * adapter up to a timeout; if it throws or times out, fall back to record-only
83
- * ALLOW and raise `onUnavailable`. Preserves "never block" for everyone, while
84
- * giving an adapter-configured org a real gate.
109
+ * adapter up to a timeout; if it throws or times out, raise `onUnavailable`
110
+ * and answer per `opts.unavailable` — DENY unless the caller chose otherwise.
111
+ *
112
+ * Until 0.2.0 this fell back to ALLOW unconditionally ("never block"). That
113
+ * made the gate suitable only where enforcement was optional: a mandatory
114
+ * boundary that fails open is not a boundary. The record-only default for
115
+ * orgs with NO adapter is unchanged — `recordOnly` still answers ALLOW — but
116
+ * an adapter that is configured and unreachable now fails closed by default.
85
117
  */
86
118
  export declare function enforce(decision: DecisionInput, adapter: EnforcementAdapter, opts?: EnforceOptions): Promise<EnforcementResult>;
87
119
  /** Reject if the promise does not settle within `ms`. */