@flashyid/sdk 0.1.1
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/LICENSE +202 -0
- package/README.md +171 -0
- package/dist/cjs/enforce/gate.js +81 -0
- package/dist/cjs/grants/fromCharter.js +36 -0
- package/dist/cjs/grants/grants.js +227 -0
- package/dist/cjs/grants/index.js +37 -0
- package/dist/cjs/grants/subject.js +107 -0
- package/dist/cjs/grants/types.js +24 -0
- package/dist/cjs/index.js +49 -0
- package/dist/cjs/init/charterGrants.js +83 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/sdk/index.js +27 -0
- package/dist/cjs/sdk/sign.js +22 -0
- package/dist/cjs/sdk/verify.js +138 -0
- package/dist/enforce/gate.d.ts +88 -0
- package/dist/enforce/gate.js +74 -0
- package/dist/grants/fromCharter.d.ts +43 -0
- package/dist/grants/fromCharter.js +33 -0
- package/dist/grants/grants.d.ts +93 -0
- package/dist/grants/grants.js +220 -0
- package/dist/grants/index.d.ts +16 -0
- package/dist/grants/index.js +14 -0
- package/dist/grants/subject.d.ts +78 -0
- package/dist/grants/subject.js +99 -0
- package/dist/grants/types.d.ts +83 -0
- package/dist/grants/types.js +20 -0
- package/dist/index.d.ts +18 -0
- package/dist/index.js +18 -0
- package/dist/init/charterGrants.d.ts +96 -0
- package/dist/init/charterGrants.js +78 -0
- package/dist/init/cli.d.ts +23 -0
- package/dist/init/cli.js +102 -0
- package/dist/sdk/index.d.ts +16 -0
- package/dist/sdk/index.js +13 -0
- package/dist/sdk/sign.d.ts +42 -0
- package/dist/sdk/sign.js +19 -0
- package/dist/sdk/verify.d.ts +85 -0
- package/dist/sdk/verify.js +134 -0
- package/docs/enforcement-gate.md +56 -0
- package/package.json +63 -0
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.issueRoot = issueRoot;
|
|
4
|
+
exports.attenuate = attenuate;
|
|
5
|
+
exports.verifyChain = verifyChain;
|
|
6
|
+
exports.permits = permits;
|
|
7
|
+
exports.rootsWithin = rootsWithin;
|
|
8
|
+
const types_js_1 = require("./types.js");
|
|
9
|
+
/**
|
|
10
|
+
* The grant kernel — pure functions over a delegation chain.
|
|
11
|
+
*
|
|
12
|
+
* Three invariants, and every one of them is enforced here rather than trusted:
|
|
13
|
+
* 1. A chain only narrows. No link grants a scope, resource, or looser limit
|
|
14
|
+
* than the link above it (`attenuate` refuses to build one; `verifyChain`
|
|
15
|
+
* refuses to accept one that arrived by any other route).
|
|
16
|
+
* 2. Effective expiry is the minimum across the whole chain — a long-lived
|
|
17
|
+
* root does not extend a short-lived leaf.
|
|
18
|
+
* 3. Revocation walks down — revoking any link invalidates it and everything
|
|
19
|
+
* delegated from it.
|
|
20
|
+
*
|
|
21
|
+
* Time is an argument (`nowSec`), never read from a clock, so verification is
|
|
22
|
+
* deterministic and testable, and an auditor re-checking a historical decision
|
|
23
|
+
* evaluates it at the time it was made.
|
|
24
|
+
*/
|
|
25
|
+
function refuse(code, at, detail) {
|
|
26
|
+
return { ok: false, code, at, detail };
|
|
27
|
+
}
|
|
28
|
+
/** Is `child` a subset of `parent`? (order-independent) */
|
|
29
|
+
function isSubset(child, parent) {
|
|
30
|
+
const p = new Set(parent);
|
|
31
|
+
return child.every((c) => p.has(c));
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Is `child`'s limit no looser than `parent`'s? A tighter or equal child is
|
|
35
|
+
* fine; a child that raises the approval bar or the spend ceiling widens.
|
|
36
|
+
*/
|
|
37
|
+
function limitWithin(child, parent) {
|
|
38
|
+
// approval bar: a parent that requires approval at/above HIGH may not be
|
|
39
|
+
// relaxed by a child to CRITICAL-only. Absent parent bar = no constraint;
|
|
40
|
+
// absent child bar under a present parent bar = the child dropped a required
|
|
41
|
+
// control, which is a widening.
|
|
42
|
+
if (parent.approval_at_or_above !== undefined) {
|
|
43
|
+
if (child.approval_at_or_above === undefined)
|
|
44
|
+
return false;
|
|
45
|
+
if ((0, types_js_1.impactRank)(child.approval_at_or_above) > (0, types_js_1.impactRank)(parent.approval_at_or_above))
|
|
46
|
+
return false;
|
|
47
|
+
}
|
|
48
|
+
// spend ceiling: a child may only lower it. Absent parent ceiling = no
|
|
49
|
+
// constraint; a child ceiling above an existing parent ceiling widens.
|
|
50
|
+
if (parent.spend_max !== undefined) {
|
|
51
|
+
if (child.spend_max === undefined)
|
|
52
|
+
return false;
|
|
53
|
+
if (child.spend_max > parent.spend_max)
|
|
54
|
+
return false;
|
|
55
|
+
}
|
|
56
|
+
return true;
|
|
57
|
+
}
|
|
58
|
+
/** The tighter of two limits, field by field. */
|
|
59
|
+
function tightestLimit(a, b) {
|
|
60
|
+
const out = {};
|
|
61
|
+
const bars = [a.approval_at_or_above, b.approval_at_or_above].filter((x) => x !== undefined);
|
|
62
|
+
if (bars.length)
|
|
63
|
+
out.approval_at_or_above = bars.reduce((lo, x) => ((0, types_js_1.impactRank)(x) < (0, types_js_1.impactRank)(lo) ? x : lo));
|
|
64
|
+
const caps = [a.spend_max, b.spend_max].filter((x) => x !== undefined);
|
|
65
|
+
if (caps.length)
|
|
66
|
+
out.spend_max = Math.min(...caps);
|
|
67
|
+
return out;
|
|
68
|
+
}
|
|
69
|
+
/** Mint the root link of a chain, issued from the accountable human. */
|
|
70
|
+
function issueRoot(input) {
|
|
71
|
+
return [
|
|
72
|
+
{
|
|
73
|
+
iss: input.rootHuman,
|
|
74
|
+
sub: input.holder,
|
|
75
|
+
scp: [...input.scp],
|
|
76
|
+
res: [...input.res],
|
|
77
|
+
lim: input.lim ? { ...input.lim } : {},
|
|
78
|
+
iat: input.iat,
|
|
79
|
+
exp: input.exp,
|
|
80
|
+
jti: input.jti,
|
|
81
|
+
},
|
|
82
|
+
];
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Append an attenuated link. Refuses (`chain_widened`) rather than silently
|
|
86
|
+
* clamping when the requested child exceeds the parent — a caller asking for
|
|
87
|
+
* more than it holds is a bug to surface, not to paper over. Expiry is the one
|
|
88
|
+
* field capped rather than refused: a child asking to outlive its parent gets
|
|
89
|
+
* the parent's expiry, since the effective expiry would be the min anyway.
|
|
90
|
+
*/
|
|
91
|
+
function attenuate(chain, input) {
|
|
92
|
+
const parent = chain[chain.length - 1];
|
|
93
|
+
if (!parent)
|
|
94
|
+
return refuse('empty_chain');
|
|
95
|
+
const scp = input.scp ?? [...parent.scp];
|
|
96
|
+
const res = input.res ?? [...parent.res];
|
|
97
|
+
const lim = input.lim ?? { ...parent.lim };
|
|
98
|
+
if (!isSubset(scp, parent.scp))
|
|
99
|
+
return refuse('chain_widened', chain.length, 'scope widened');
|
|
100
|
+
if (!isSubset(res, parent.res))
|
|
101
|
+
return refuse('chain_widened', chain.length, 'resource widened');
|
|
102
|
+
if (!limitWithin(lim, parent.lim))
|
|
103
|
+
return refuse('chain_widened', chain.length, 'limit loosened');
|
|
104
|
+
const child = {
|
|
105
|
+
iss: parent.sub, // the parent's holder is this child's issuer
|
|
106
|
+
sub: input.holder,
|
|
107
|
+
scp,
|
|
108
|
+
res,
|
|
109
|
+
lim,
|
|
110
|
+
iat: input.iat,
|
|
111
|
+
exp: Math.min(input.exp, parent.exp), // never outlive the parent
|
|
112
|
+
jti: input.jti,
|
|
113
|
+
};
|
|
114
|
+
return [...chain, child];
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* Verify a chain end to end and resolve the authority in effect, or refuse with
|
|
118
|
+
* the first reason it fails. Enforces continuity (each issuer is the holder
|
|
119
|
+
* above), the narrowing invariant at every hop, expiry at `nowSec`, and
|
|
120
|
+
* (optionally) revocation. Independent of how the chain was built — a chain
|
|
121
|
+
* that widened by any route is caught here, which is why attenuate's guard is
|
|
122
|
+
* not the only line of defense.
|
|
123
|
+
*/
|
|
124
|
+
function verifyChain(chain, nowSec, revokedJtis = new Set()) {
|
|
125
|
+
const first = chain[0];
|
|
126
|
+
if (!first)
|
|
127
|
+
return refuse('empty_chain');
|
|
128
|
+
let effLim = { ...first.lim };
|
|
129
|
+
let effExp = first.exp;
|
|
130
|
+
for (let i = 0; i < chain.length; i++) {
|
|
131
|
+
const link = chain[i];
|
|
132
|
+
if (!link)
|
|
133
|
+
continue; // unreachable given the loop bound; satisfies strict indexing
|
|
134
|
+
// Revocation walks down: a revoked link, or any ancestor, kills the chain
|
|
135
|
+
// from that point. Checked ancestor-first, so the refusal points at the
|
|
136
|
+
// highest revoked link.
|
|
137
|
+
if (revokedJtis.has(link.jti))
|
|
138
|
+
return refuse('revoked', i);
|
|
139
|
+
if (link.exp <= nowSec)
|
|
140
|
+
return refuse('expired', i);
|
|
141
|
+
if (i > 0) {
|
|
142
|
+
const parent = chain[i - 1];
|
|
143
|
+
if (!parent)
|
|
144
|
+
return refuse('broken_chain', i);
|
|
145
|
+
if (link.iss !== parent.sub)
|
|
146
|
+
return refuse('broken_chain', i, 'issuer is not the holder above');
|
|
147
|
+
if (!isSubset(link.scp, parent.scp))
|
|
148
|
+
return refuse('chain_widened', i, 'scope widened');
|
|
149
|
+
if (!isSubset(link.res, parent.res))
|
|
150
|
+
return refuse('chain_widened', i, 'resource widened');
|
|
151
|
+
if (!limitWithin(link.lim, parent.lim))
|
|
152
|
+
return refuse('chain_widened', i, 'limit loosened');
|
|
153
|
+
effLim = tightestLimit(effLim, link.lim);
|
|
154
|
+
effExp = Math.min(effExp, link.exp);
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
const leaf = chain[chain.length - 1];
|
|
158
|
+
if (!leaf)
|
|
159
|
+
return refuse('empty_chain');
|
|
160
|
+
const effective = {
|
|
161
|
+
ok: true,
|
|
162
|
+
root: first.iss,
|
|
163
|
+
holder: leaf.sub,
|
|
164
|
+
scp: [...leaf.scp],
|
|
165
|
+
res: [...leaf.res],
|
|
166
|
+
lim: effLim,
|
|
167
|
+
exp: effExp,
|
|
168
|
+
chain: chain.map((l) => l.jti),
|
|
169
|
+
};
|
|
170
|
+
return effective;
|
|
171
|
+
}
|
|
172
|
+
/**
|
|
173
|
+
* Does a verified chain actually authorize a specific action? Separated from
|
|
174
|
+
* verifyChain so the two questions — "is this chain sound?" and "does it permit
|
|
175
|
+
* *this*?" — refuse with distinct reasons (`out_of_mandate` here, structural
|
|
176
|
+
* codes there).
|
|
177
|
+
*
|
|
178
|
+
* The human-approval bar is enforced here, not merely read: a demand whose
|
|
179
|
+
* `impact` is at or above the chain's effective `approval_at_or_above` is
|
|
180
|
+
* refused with `approval_required` — never a silent `true` — because this
|
|
181
|
+
* function cannot see whether a human co-signed. `permits` returning `true`
|
|
182
|
+
* therefore means "proceed without a co-signature". A caller that *can* route
|
|
183
|
+
* to a human (the enforcement gate's `evaluateGrant`) treats the
|
|
184
|
+
* `approval_required` refusal as ESCALATE rather than DENY; a caller that
|
|
185
|
+
* cannot (`authorize`) surfaces it as a refusal. A demand with no `impact`
|
|
186
|
+
* declared is treated as below the bar — impact classification is the
|
|
187
|
+
* caller's contract with its action vocabulary.
|
|
188
|
+
*/
|
|
189
|
+
function permits(effective, demand) {
|
|
190
|
+
if (!effective.scp.includes(demand.scope))
|
|
191
|
+
return refuse('out_of_mandate', undefined, `scope ${demand.scope} not granted`);
|
|
192
|
+
if (demand.resource !== undefined && !effective.res.includes(demand.resource)) {
|
|
193
|
+
return refuse('out_of_mandate', undefined, `resource ${demand.resource} not granted`);
|
|
194
|
+
}
|
|
195
|
+
if (demand.amount !== undefined && effective.lim.spend_max !== undefined && demand.amount > effective.lim.spend_max) {
|
|
196
|
+
return refuse('out_of_mandate', undefined, 'amount exceeds spend_max');
|
|
197
|
+
}
|
|
198
|
+
const bar = effective.lim.approval_at_or_above;
|
|
199
|
+
if (bar !== undefined && demand.impact !== undefined && (0, types_js_1.impactRank)(demand.impact) >= (0, types_js_1.impactRank)(bar)) {
|
|
200
|
+
return refuse('approval_required', undefined, `impact ${demand.impact} needs approval at or above ${bar}`);
|
|
201
|
+
}
|
|
202
|
+
return true;
|
|
203
|
+
}
|
|
204
|
+
/**
|
|
205
|
+
* Does a sound chain root at a principal this relying party actually accepts?
|
|
206
|
+
*
|
|
207
|
+
* Chain soundness (verifyChain) proves a chain only ever narrows and is held by
|
|
208
|
+
* whoever it says — but a sound chain can root at *any* human. On the mesh that
|
|
209
|
+
* is not enough: an agent signing in at org B with a genuine Flashy ID assertion
|
|
210
|
+
* could carry a chain rooted at any accountable human anywhere. A relying party
|
|
211
|
+
* has to pin the roots it will honour, or "verified" quietly means "verified to
|
|
212
|
+
* belong to someone, somewhere". This is that pin, kept separate from permits so
|
|
213
|
+
* an untrusted root refuses with its own reason rather than looking like an
|
|
214
|
+
* out-of-mandate scope.
|
|
215
|
+
*
|
|
216
|
+
* `trustedRoots` is the set of `iss` values (the accountable humans, or org ids)
|
|
217
|
+
* whose authority this party accepts — typically the `accountableTo` of every
|
|
218
|
+
* AAO charter it federates with. An empty set trusts nobody and refuses every
|
|
219
|
+
* chain, which is the safe direction: a relying party that forgot to configure
|
|
220
|
+
* its roots rejects rather than admits.
|
|
221
|
+
*/
|
|
222
|
+
function rootsWithin(effective, trustedRoots) {
|
|
223
|
+
const trusted = trustedRoots instanceof Set ? trustedRoots : new Set(trustedRoots);
|
|
224
|
+
if (trusted.has(effective.root))
|
|
225
|
+
return true;
|
|
226
|
+
return refuse('untrusted_root', 0, `chain roots at ${effective.root}, which this relying party does not accept`);
|
|
227
|
+
}
|
|
@@ -0,0 +1,37 @@
|
|
|
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 __exportStar = (this && this.__exportStar) || function(m, exports) {
|
|
14
|
+
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
|
|
15
|
+
};
|
|
16
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
17
|
+
exports.grantFromCharterRole = exports.rootsWithin = exports.permits = exports.verifyChain = exports.attenuate = exports.issueRoot = void 0;
|
|
18
|
+
/**
|
|
19
|
+
* @flashyid/grants — the delegated-authority grant kernel.
|
|
20
|
+
*
|
|
21
|
+
* Pure functions over a delegation chain: issue a root from an accountable
|
|
22
|
+
* human, attenuate it down to an agent, verify the chain, and check whether it
|
|
23
|
+
* permits a specific action. No I/O, no clock, no dependency — the same code
|
|
24
|
+
* runs in the issuer, a relying party, and a stranger's audit script.
|
|
25
|
+
*
|
|
26
|
+
* The charter is already the grant: grantFromCharterRole maps an AAO chartered
|
|
27
|
+
* role onto a root grant with no new policy language.
|
|
28
|
+
*/
|
|
29
|
+
__exportStar(require("./types.js"), exports);
|
|
30
|
+
var grants_js_1 = require("./grants.js");
|
|
31
|
+
Object.defineProperty(exports, "issueRoot", { enumerable: true, get: function () { return grants_js_1.issueRoot; } });
|
|
32
|
+
Object.defineProperty(exports, "attenuate", { enumerable: true, get: function () { return grants_js_1.attenuate; } });
|
|
33
|
+
Object.defineProperty(exports, "verifyChain", { enumerable: true, get: function () { return grants_js_1.verifyChain; } });
|
|
34
|
+
Object.defineProperty(exports, "permits", { enumerable: true, get: function () { return grants_js_1.permits; } });
|
|
35
|
+
Object.defineProperty(exports, "rootsWithin", { enumerable: true, get: function () { return grants_js_1.rootsWithin; } });
|
|
36
|
+
var fromCharter_js_1 = require("./fromCharter.js");
|
|
37
|
+
Object.defineProperty(exports, "grantFromCharterRole", { enumerable: true, get: function () { return fromCharter_js_1.grantFromCharterRole; } });
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* What a machine is called when Flashy ID authenticates it.
|
|
4
|
+
*
|
|
5
|
+
* `GrantLink.sub` has always been documented as "a human email, an org id, or
|
|
6
|
+
* an agent surrogate", and until 2026-08-31 the agent surrogate existed only in
|
|
7
|
+
* this suite's fixtures — `agent:flashyos/settlement`, eighteen occurrences,
|
|
8
|
+
* every one of them a test. Nothing constructed one, nothing validated one, and
|
|
9
|
+
* nothing could tell you whether a given string was one.
|
|
10
|
+
*
|
|
11
|
+
* That is the same defect the estate's directory had a week earlier and for the
|
|
12
|
+
* same reason: an identifier that reads as an identity and resolves to nothing.
|
|
13
|
+
* The directory's version was 2,478 edges signed by ids no fragment declared.
|
|
14
|
+
* This is the layer above it — the identities those emitters would authenticate
|
|
15
|
+
* as — and it had no format at all, so linking the two would have meant
|
|
16
|
+
* inventing one at the call site, in thirty repositories, each free to get it
|
|
17
|
+
* subtly wrong.
|
|
18
|
+
*
|
|
19
|
+
* So the format is declared once, here, with a constructor and a parser.
|
|
20
|
+
*
|
|
21
|
+
* ── The shape ───────────────────────────────────────────────────────────────
|
|
22
|
+
*
|
|
23
|
+
* agent:<org>/<name>
|
|
24
|
+
*
|
|
25
|
+
* `org` is the organisation the machine acts for; `name` is what it does. Both
|
|
26
|
+
* are bare lowercase slugs. The colon separates the scheme from the identity
|
|
27
|
+
* the way a URI does, and the slash says the machine belongs to the org rather
|
|
28
|
+
* than standing beside it — an agent has no authority of its own, which is the
|
|
29
|
+
* whole doctrine: it acts *for* somebody and the somebody answers.
|
|
30
|
+
*
|
|
31
|
+
* ── Why it is not the directory's `agent/<slug>` ────────────────────────────
|
|
32
|
+
*
|
|
33
|
+
* They are different things and collapsing them would lose the difference. The
|
|
34
|
+
* directory's `agent/flashyos-ci` is a *record* — a row saying this machine
|
|
35
|
+
* exists and the org operates it. This is a *subject* — the principal an
|
|
36
|
+
* assertion is minted for and a grant chain is held by. One is a claim about
|
|
37
|
+
* the world; the other is something you can authenticate as.
|
|
38
|
+
*
|
|
39
|
+
* `fromDirectoryId` is the bridge, and it is a function rather than a
|
|
40
|
+
* convention so that the mapping is checkable in both directions instead of
|
|
41
|
+
* being retyped by whoever is writing an emitter that afternoon.
|
|
42
|
+
*/
|
|
43
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
44
|
+
exports.isAgentSubject = exports.AGENT_SUBJECT = void 0;
|
|
45
|
+
exports.agentSubject = agentSubject;
|
|
46
|
+
exports.parseAgentSubject = parseAgentSubject;
|
|
47
|
+
exports.fromDirectoryId = fromDirectoryId;
|
|
48
|
+
exports.toDirectoryId = toDirectoryId;
|
|
49
|
+
/** A bare lowercase slug: what both halves of a surrogate must be. */
|
|
50
|
+
const SLUG = /^[a-z0-9][a-z0-9._-]*$/;
|
|
51
|
+
/** A well-formed agent surrogate. */
|
|
52
|
+
exports.AGENT_SUBJECT = /^agent:([a-z0-9][a-z0-9._-]*)\/([a-z0-9][a-z0-9._-]*)$/;
|
|
53
|
+
/**
|
|
54
|
+
* Build the subject a machine authenticates as.
|
|
55
|
+
*
|
|
56
|
+
* Throws rather than returning something plausible. A malformed subject is
|
|
57
|
+
* indistinguishable from a well-formed one at every layer above this — it
|
|
58
|
+
* would be minted into an assertion, carried in a chain, and refused only at
|
|
59
|
+
* the relying party, with a message about the chain rather than the name.
|
|
60
|
+
*/
|
|
61
|
+
function agentSubject(org, name) {
|
|
62
|
+
if (!SLUG.test(org ?? ''))
|
|
63
|
+
throw new TypeError(`an agent's org must be a bare lowercase slug, got "${org}"`);
|
|
64
|
+
if (!SLUG.test(name ?? ''))
|
|
65
|
+
throw new TypeError(`an agent's name must be a bare lowercase slug, got "${name}"`);
|
|
66
|
+
return `agent:${org}/${name}`;
|
|
67
|
+
}
|
|
68
|
+
/** Read a subject back, or null if it is not one. Never throws. */
|
|
69
|
+
function parseAgentSubject(subject) {
|
|
70
|
+
const m = exports.AGENT_SUBJECT.exec(subject ?? '');
|
|
71
|
+
// Both groups are non-optional in the pattern, so a match always has them.
|
|
72
|
+
// `noUncheckedIndexedAccess` cannot see that, and asserting it here is
|
|
73
|
+
// cheaper than a pattern shaped to satisfy the compiler.
|
|
74
|
+
return m && m[1] !== undefined && m[2] !== undefined ? { org: m[1], name: m[2] } : null;
|
|
75
|
+
}
|
|
76
|
+
/** True when this subject is an agent rather than a person or an organisation. */
|
|
77
|
+
const isAgentSubject = (subject) => exports.AGENT_SUBJECT.test(subject ?? '');
|
|
78
|
+
exports.isAgentSubject = isAgentSubject;
|
|
79
|
+
/**
|
|
80
|
+
* The subject a directory Agent record authenticates as.
|
|
81
|
+
*
|
|
82
|
+
* The estate's directory names its emitters `agent/<org>-ci` — the org's slug,
|
|
83
|
+
* a hyphen, and what the machine does. That convention is the directory's and
|
|
84
|
+
* this function reads it rather than restating it: given the org slug, the
|
|
85
|
+
* remainder of the directory id is the machine's name.
|
|
86
|
+
*
|
|
87
|
+
* Returns null rather than guessing when the id does not belong to that org.
|
|
88
|
+
* A subject derived from a mismatched pair would authenticate as a machine of
|
|
89
|
+
* an organisation that never declared it, which is worse than no subject: it
|
|
90
|
+
* is a working credential pointing at the wrong accountable party.
|
|
91
|
+
*/
|
|
92
|
+
function fromDirectoryId(directoryId, orgSlug) {
|
|
93
|
+
const bare = (directoryId ?? '').startsWith('agent/') ? directoryId.slice('agent/'.length) : null;
|
|
94
|
+
if (bare === null || !SLUG.test(orgSlug ?? ''))
|
|
95
|
+
return null;
|
|
96
|
+
if (!bare.startsWith(`${orgSlug}-`))
|
|
97
|
+
return null;
|
|
98
|
+
const name = bare.slice(orgSlug.length + 1);
|
|
99
|
+
if (!SLUG.test(name))
|
|
100
|
+
return null;
|
|
101
|
+
return agentSubject(orgSlug, name);
|
|
102
|
+
}
|
|
103
|
+
/** The directory id a subject corresponds to — the same bridge, backwards. */
|
|
104
|
+
function toDirectoryId(subject) {
|
|
105
|
+
const parsed = parseAgentSubject(subject);
|
|
106
|
+
return parsed ? `agent/${parsed.org}-${parsed.name}` : null;
|
|
107
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* The delegated-authority grant model (Flashy ID spec v0.3, delegation profile).
|
|
4
|
+
*
|
|
5
|
+
* A grant is not a single token — it is a *chain*. The root link is issued from
|
|
6
|
+
* the human named `accountableTo` in an organization's charter; every link
|
|
7
|
+
* below it is an attenuation, handed from one holder to the next, and no link
|
|
8
|
+
* may ever grant more than the one above it. That single rule — a chain only
|
|
9
|
+
* narrows — is what lets an agent act on a person's authority without ever
|
|
10
|
+
* being able to exceed it.
|
|
11
|
+
*
|
|
12
|
+
* These are pure data types and the kernel over them (grants.ts) is pure
|
|
13
|
+
* functions: no I/O, no network, no clock of its own (time is passed in). That
|
|
14
|
+
* is deliberate — the whole thing is verifiable on a laptop, and the same code
|
|
15
|
+
* runs in the issuer, in a relying party, and in a stranger's audit script.
|
|
16
|
+
*/
|
|
17
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
18
|
+
exports.IMPACT_ORDER = void 0;
|
|
19
|
+
exports.impactRank = impactRank;
|
|
20
|
+
/** Severity ladder, low → high. Matches the AAO charter's Impact. */
|
|
21
|
+
exports.IMPACT_ORDER = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
|
|
22
|
+
function impactRank(i) {
|
|
23
|
+
return exports.IMPACT_ORDER.indexOf(i);
|
|
24
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
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 __exportStar = (this && this.__exportStar) || function(m, exports) {
|
|
14
|
+
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
|
|
15
|
+
};
|
|
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;
|
|
18
|
+
/**
|
|
19
|
+
* @flashyid/sdk — the relying-party surface for Flashy ID delegated authority.
|
|
20
|
+
*
|
|
21
|
+
* Verify that an assertion is genuinely from Flashy ID, and that the delegation
|
|
22
|
+
* it carries authorizes a specific action — from one import, holding no secret
|
|
23
|
+
* (only the public JWKS). Plus the grant kernel (issue / attenuate / verify /
|
|
24
|
+
* permits), and the charter→grants mapping the `flashyid init` command uses.
|
|
25
|
+
*
|
|
26
|
+
* Pure and standards-based: OIDC ID tokens (EdDSA/JWS) for the assertion, and a
|
|
27
|
+
* delegation-chain profile whose one rule is that a chain only ever narrows.
|
|
28
|
+
*/
|
|
29
|
+
__exportStar(require("./sdk/index.js"), exports);
|
|
30
|
+
var gate_js_1 = require("./enforce/gate.js");
|
|
31
|
+
Object.defineProperty(exports, "evaluateGrant", { enumerable: true, get: function () { return gate_js_1.evaluateGrant; } });
|
|
32
|
+
Object.defineProperty(exports, "enforce", { enumerable: true, get: function () { return gate_js_1.enforce; } });
|
|
33
|
+
Object.defineProperty(exports, "withTimeout", { enumerable: true, get: function () { return gate_js_1.withTimeout; } });
|
|
34
|
+
Object.defineProperty(exports, "recordOnly", { enumerable: true, get: function () { return gate_js_1.recordOnly; } });
|
|
35
|
+
Object.defineProperty(exports, "grantAdapter", { enumerable: true, get: function () { return gate_js_1.grantAdapter; } });
|
|
36
|
+
// What a machine is called when Flashy ID authenticates it. The agent
|
|
37
|
+
// surrogate lived only in this suite's fixtures until 2026-08-31; it is
|
|
38
|
+
// exported so the estate's directory can link to it rather than invent it.
|
|
39
|
+
var subject_js_1 = require("./grants/subject.js");
|
|
40
|
+
Object.defineProperty(exports, "agentSubject", { enumerable: true, get: function () { return subject_js_1.agentSubject; } });
|
|
41
|
+
Object.defineProperty(exports, "parseAgentSubject", { enumerable: true, get: function () { return subject_js_1.parseAgentSubject; } });
|
|
42
|
+
Object.defineProperty(exports, "isAgentSubject", { enumerable: true, get: function () { return subject_js_1.isAgentSubject; } });
|
|
43
|
+
Object.defineProperty(exports, "fromDirectoryId", { enumerable: true, get: function () { return subject_js_1.fromDirectoryId; } });
|
|
44
|
+
Object.defineProperty(exports, "toDirectoryId", { enumerable: true, get: function () { return subject_js_1.toDirectoryId; } });
|
|
45
|
+
Object.defineProperty(exports, "AGENT_SUBJECT", { enumerable: true, get: function () { return subject_js_1.AGENT_SUBJECT; } });
|
|
46
|
+
var charterGrants_js_1 = require("./init/charterGrants.js");
|
|
47
|
+
Object.defineProperty(exports, "grantsFromCharter", { enumerable: true, get: function () { return charterGrants_js_1.grantsFromCharter; } });
|
|
48
|
+
Object.defineProperty(exports, "summarizeGrants", { enumerable: true, get: function () { return charterGrants_js_1.summarizeGrants; } });
|
|
49
|
+
Object.defineProperty(exports, "trustedRootsFromCharters", { enumerable: true, get: function () { return charterGrants_js_1.trustedRootsFromCharters; } });
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.trustedRootsFromCharters = trustedRootsFromCharters;
|
|
4
|
+
exports.grantsFromCharter = grantsFromCharter;
|
|
5
|
+
exports.summarizeGrants = summarizeGrants;
|
|
6
|
+
const fromCharter_js_1 = require("../grants/fromCharter.js");
|
|
7
|
+
const grants_js_1 = require("../grants/grants.js");
|
|
8
|
+
/**
|
|
9
|
+
* The roots a relying party accepts, derived from the charters it federates with.
|
|
10
|
+
*
|
|
11
|
+
* This is the mesh binding made concrete. On the network an agent from org A
|
|
12
|
+
* signs in at org B; org B verifies the assertion is genuinely from Flashy ID,
|
|
13
|
+
* but a genuine assertion can carry a chain rooted at any accountable human
|
|
14
|
+
* anywhere. Org B decides *whose* authority it honours by naming the orgs it
|
|
15
|
+
* federates with — and every AAO charter already names the one human every one
|
|
16
|
+
* of its chains roots at: `accountableTo`. Passing this set to `authorize`'s
|
|
17
|
+
* `trustedRoots` is how "sign in with Flashy ID" stops meaning "belongs to
|
|
18
|
+
* someone" and starts meaning "belongs to someone this org agreed to trust".
|
|
19
|
+
*
|
|
20
|
+
* A charter with no `accountableTo` contributes nothing rather than a blank
|
|
21
|
+
* root, because an empty string would silently trust every chain that forgot to
|
|
22
|
+
* set one.
|
|
23
|
+
*/
|
|
24
|
+
function trustedRootsFromCharters(charters) {
|
|
25
|
+
const roots = new Set();
|
|
26
|
+
for (const charter of charters) {
|
|
27
|
+
const root = charter?.accountableTo?.trim();
|
|
28
|
+
if (root)
|
|
29
|
+
roots.add(root);
|
|
30
|
+
}
|
|
31
|
+
return roots;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Map an entire charter to grants. A role whose capability is unmapped (under a
|
|
35
|
+
* registry) collects into `refusals` rather than issuing a narrower grant
|
|
36
|
+
* quietly — an init run with any refusal is not `ok`, and the command fails
|
|
37
|
+
* loudly rather than registering a client with silently-dropped authority.
|
|
38
|
+
*/
|
|
39
|
+
function grantsFromCharter(charter, opts) {
|
|
40
|
+
const holderFor = opts.holderFor ?? ((role) => `${charter.slug ?? 'org'}/${role}`);
|
|
41
|
+
const grants = [];
|
|
42
|
+
const refusals = [];
|
|
43
|
+
for (const role of charter.roles) {
|
|
44
|
+
const holder = holderFor(role.name);
|
|
45
|
+
const result = (0, fromCharter_js_1.grantFromCharterRole)({
|
|
46
|
+
accountableTo: charter.accountableTo,
|
|
47
|
+
role,
|
|
48
|
+
holder,
|
|
49
|
+
iat: opts.iat,
|
|
50
|
+
exp: opts.exp,
|
|
51
|
+
jti: opts.jtiFor(role.name),
|
|
52
|
+
scopeRegistry: opts.scopeRegistry,
|
|
53
|
+
});
|
|
54
|
+
if ('ok' in result) {
|
|
55
|
+
refusals.push({ role: role.name, refusal: result });
|
|
56
|
+
}
|
|
57
|
+
else {
|
|
58
|
+
grants.push({ role: role.name, holder, grant: result });
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
return { grants, refusals, ok: refusals.length === 0 };
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* A one-line-per-role summary of an init run, in the shape the command prints.
|
|
65
|
+
* Verifies each grant as it renders — a grant that maps but does not verify is a
|
|
66
|
+
* bug in the kernel, and the summary surfaces it rather than hiding it.
|
|
67
|
+
*/
|
|
68
|
+
function summarizeGrants(result, nowSec) {
|
|
69
|
+
const lines = [];
|
|
70
|
+
for (const { role, grant } of result.grants) {
|
|
71
|
+
const v = (0, grants_js_1.verifyChain)(grant, nowSec);
|
|
72
|
+
const leaf = grant[grant.length - 1];
|
|
73
|
+
if (!leaf)
|
|
74
|
+
continue;
|
|
75
|
+
const status = v.ok ? 'ok' : `INVALID:${v.code}`;
|
|
76
|
+
const approval = leaf.lim.approval_at_or_above ?? '—';
|
|
77
|
+
lines.push(`${role.padEnd(22)} ${leaf.scp.join(', ')} [${approval}] ${status}`);
|
|
78
|
+
}
|
|
79
|
+
for (const { role, refusal } of result.refusals) {
|
|
80
|
+
lines.push(`${role.padEnd(22)} REFUSED: ${refusal.code}${refusal.detail ? ` (${refusal.detail})` : ''}`);
|
|
81
|
+
}
|
|
82
|
+
return lines;
|
|
83
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"type":"commonjs"}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"use strict";
|
|
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;
|
|
4
|
+
/**
|
|
5
|
+
* @flashyid/sdk — verify a Flashy ID assertion and the delegation it carries.
|
|
6
|
+
*
|
|
7
|
+
* The whole consumer surface a relying party needs:
|
|
8
|
+
* - verifyAssertion: is this genuinely from Flashy ID? (signature, iss, aud, exp)
|
|
9
|
+
* - authorize: and does its delegation permit *this* action?
|
|
10
|
+
*
|
|
11
|
+
* plus the grant kernel re-exported, so a consumer that wants to inspect or
|
|
12
|
+
* re-check a chain itself has one import for everything.
|
|
13
|
+
*/
|
|
14
|
+
var verify_js_1 = require("./verify.js");
|
|
15
|
+
Object.defineProperty(exports, "verifyAssertion", { enumerable: true, get: function () { return verify_js_1.verifyAssertion; } });
|
|
16
|
+
Object.defineProperty(exports, "authorize", { enumerable: true, get: function () { return verify_js_1.authorize; } });
|
|
17
|
+
var sign_js_1 = require("./sign.js");
|
|
18
|
+
Object.defineProperty(exports, "signAssertion", { enumerable: true, get: function () { return sign_js_1.signAssertion; } });
|
|
19
|
+
var index_js_1 = require("../grants/index.js");
|
|
20
|
+
Object.defineProperty(exports, "issueRoot", { enumerable: true, get: function () { return index_js_1.issueRoot; } });
|
|
21
|
+
Object.defineProperty(exports, "attenuate", { enumerable: true, get: function () { return index_js_1.attenuate; } });
|
|
22
|
+
Object.defineProperty(exports, "verifyChain", { enumerable: true, get: function () { return index_js_1.verifyChain; } });
|
|
23
|
+
Object.defineProperty(exports, "permits", { enumerable: true, get: function () { return index_js_1.permits; } });
|
|
24
|
+
Object.defineProperty(exports, "rootsWithin", { enumerable: true, get: function () { return index_js_1.rootsWithin; } });
|
|
25
|
+
Object.defineProperty(exports, "grantFromCharterRole", { enumerable: true, get: function () { return index_js_1.grantFromCharterRole; } });
|
|
26
|
+
Object.defineProperty(exports, "impactRank", { enumerable: true, get: function () { return index_js_1.impactRank; } });
|
|
27
|
+
Object.defineProperty(exports, "IMPACT_ORDER", { enumerable: true, get: function () { return index_js_1.IMPACT_ORDER; } });
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.signAssertion = signAssertion;
|
|
4
|
+
const jose_1 = require("jose");
|
|
5
|
+
/** Mint and sign a Flashy ID assertion, returning the compact JWS string. */
|
|
6
|
+
async function signAssertion(input) {
|
|
7
|
+
const iat = input.iatSec ?? Math.floor(Date.now() / 1000);
|
|
8
|
+
const exp = iat + (input.expiresInSec ?? 3600);
|
|
9
|
+
const payload = { ...(input.extraClaims ?? {}) };
|
|
10
|
+
if (input.delegation)
|
|
11
|
+
payload.del = input.delegation;
|
|
12
|
+
const signer = new jose_1.SignJWT(payload)
|
|
13
|
+
.setProtectedHeader({ alg: 'EdDSA', ...(input.kid ? { kid: input.kid } : {}) })
|
|
14
|
+
.setIssuer(input.issuer)
|
|
15
|
+
.setAudience(input.audience)
|
|
16
|
+
.setSubject(input.subject)
|
|
17
|
+
.setIssuedAt(iat)
|
|
18
|
+
.setExpirationTime(exp);
|
|
19
|
+
if (input.jti)
|
|
20
|
+
signer.setJti(input.jti);
|
|
21
|
+
return signer.sign(input.privateKey);
|
|
22
|
+
}
|