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