@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.
- package/README.md +195 -11
- package/dist/cjs/enforce/gate.js +50 -10
- package/dist/cjs/grants/grants.js +46 -4
- package/dist/cjs/grants/index.js +13 -1
- package/dist/cjs/grants/revocation.js +194 -0
- package/dist/cjs/index.js +9 -1
- package/dist/cjs/rail/tokens.js +136 -0
- package/dist/cjs/sdk/index.js +15 -1
- package/dist/cjs/sdk/revocation.js +84 -0
- package/dist/cjs/sdk/verify.js +18 -5
- package/dist/enforce/gate.d.ts +38 -6
- package/dist/enforce/gate.js +50 -10
- package/dist/grants/grants.d.ts +16 -4
- package/dist/grants/grants.js +46 -4
- package/dist/grants/index.d.ts +2 -0
- package/dist/grants/index.js +1 -0
- package/dist/grants/revocation.d.ts +130 -0
- package/dist/grants/revocation.js +183 -0
- package/dist/grants/types.d.ts +20 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.js +4 -0
- package/dist/init/cli.d.ts +8 -0
- package/dist/init/cli.js +42 -2
- package/dist/rail/tokens.d.ts +148 -0
- package/dist/rail/tokens.js +130 -0
- package/dist/sdk/index.d.ts +4 -2
- package/dist/sdk/index.js +2 -1
- package/dist/sdk/revocation.d.ts +51 -0
- package/dist/sdk/revocation.js +47 -0
- package/dist/sdk/verify.d.ts +10 -0
- package/dist/sdk/verify.js +18 -5
- package/docs/enforcement-gate.md +33 -16
- package/package.json +3 -3
|
@@ -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
|
+
}
|
package/dist/cjs/sdk/index.js
CHANGED
|
@@ -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
|
+
}
|
package/dist/cjs/sdk/verify.js
CHANGED
|
@@ -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.
|
|
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
|
-
|
|
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
|
}
|
package/dist/enforce/gate.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
77
|
-
*
|
|
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,
|
|
83
|
-
*
|
|
84
|
-
*
|
|
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`. */
|