@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
package/README.md
CHANGED
|
@@ -38,7 +38,7 @@ if (out === null) {
|
|
|
38
38
|
// authorized — out.result.scp / .lim / .exp
|
|
39
39
|
} else {
|
|
40
40
|
// genuine but refused → 403; out.result.code says why
|
|
41
|
-
// 'out_of_mandate' | 'approval_required' | 'untrusted_root' | 'expired' | 'revoked' | …
|
|
41
|
+
// 'out_of_mandate' | 'approval_required' | 'untrusted_root' | 'expired' | 'not_yet_valid' | 'revoked' | …
|
|
42
42
|
}
|
|
43
43
|
```
|
|
44
44
|
|
|
@@ -73,6 +73,39 @@ mandate check, so an untrusted root is never masked as a missing scope. The
|
|
|
73
73
|
underlying `rootsWithin(effective, roots)` is exported for a party that verifies
|
|
74
74
|
a chain itself.
|
|
75
75
|
|
|
76
|
+
## The rail-grant bridge, and its root-trust policy
|
|
77
|
+
|
|
78
|
+
`authorize`'s `trustedRoots` above is optional because verifying a sign-in is
|
|
79
|
+
low-stakes enough that "any root" is a legitimate default for a single
|
|
80
|
+
issuer. Minting a **rail grant** — converting a sound delegation chain into an
|
|
81
|
+
actual capped draw against Flashy Gold the estate holds — is not that kind of
|
|
82
|
+
operation, and `railGrantFromChain` does not offer the same default:
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
import { railGrantFromChain, trustedRootsFromCharters } from '@flashyid/sdk';
|
|
86
|
+
|
|
87
|
+
const trustedRoots = trustedRootsFromCharters([ourCharter]); // estate-named roots only
|
|
88
|
+
|
|
89
|
+
const jwt = await railGrantFromChain(signer, chain, {
|
|
90
|
+
grantId: 'g_123',
|
|
91
|
+
assetId: 'flashy-gold',
|
|
92
|
+
purpose: 'delegated-settlement',
|
|
93
|
+
trustedRoots, // required — refuses `untrusted_root` with no default accept-all
|
|
94
|
+
});
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
`trustedRoots` has no default and cannot be omitted — a chain that is
|
|
98
|
+
perfectly sound (`verifyChain`) and perfectly capped can still root at a
|
|
99
|
+
principal this estate never agreed to vouch spend for, and a check a caller
|
|
100
|
+
can skip by not passing an argument is, in practice, a check that doesn't
|
|
101
|
+
run. The ratified policy is **estate-named roots only**: build the set from
|
|
102
|
+
`trustedRootsFromCharters` over the charters this estate actually accounts
|
|
103
|
+
to, the same source a relying party's sign-in trust decision already draws
|
|
104
|
+
from, rather than a hand-typed list that can drift from the directory. See
|
|
105
|
+
`docs/rail-grant.md` in the flashyID server repo for the full ratification
|
|
106
|
+
and the PKI/federation reasoning behind why this is a closed allow-list
|
|
107
|
+
rather than "any sound chain."
|
|
108
|
+
|
|
76
109
|
## What's in it
|
|
77
110
|
|
|
78
111
|
- **`signAssertion(input)`** — the issuer half: mint an EdDSA assertion (JWS)
|
|
@@ -86,10 +119,21 @@ a chain itself.
|
|
|
86
119
|
Pure functions over a delegation chain; the one rule is that a chain only ever
|
|
87
120
|
narrows (three invariants: never widens, effective expiry is the minimum
|
|
88
121
|
across the chain, revocation walks down).
|
|
122
|
+
- **The revocation list** — `emptyRevocationList`, `revoke`, `revokedAsOf`,
|
|
123
|
+
`extendsList`, `validateRevocationList`, `verifyChainAgainst`, and the signed
|
|
124
|
+
form `signRevocationList` / `verifyRevocationList`. `revocation/1`: append-only,
|
|
125
|
+
signed by a person or an org with a stated reason, verified from the same
|
|
126
|
+
JWKS as an assertion. See *Runtime gating and revocation*.
|
|
89
127
|
- **Charter → grants** — `grantsFromCharter`, `grantFromCharterRole`. An AAO
|
|
90
128
|
chartered role already carries the fields a grant needs
|
|
91
129
|
(`capabilities → scp`, `worksIn → res`, `humanApprovalAtOrAbove → lim`,
|
|
92
130
|
`accountableTo → root`), so no new policy language.
|
|
131
|
+
- **`railGrantFromChain(signer, chain, extra)`** — folds a verified chain onto
|
|
132
|
+
Flashy Rails' flat spend-grant vocabulary (root = value holder, leaf =
|
|
133
|
+
spender; see *The rail-grant bridge, and its root-trust policy* below). It
|
|
134
|
+
is the one place a sound delegation chain turns into a direct draw on real
|
|
135
|
+
Flashy Gold, which is why `extra.trustedRoots` is required rather than
|
|
136
|
+
optional.
|
|
93
137
|
|
|
94
138
|
## The enforcement gate
|
|
95
139
|
|
|
@@ -105,7 +149,8 @@ import { evaluateGrant, enforce, grantAdapter, recordOnly } from '@flashyid/sdk'
|
|
|
105
149
|
const r = evaluateGrant(chain, { scope: 'seal', impact: 'CRITICAL' }, { nowSec });
|
|
106
150
|
// → { action: 'ESCALATE', escalateAtOrAbove: 'HIGH', ... }
|
|
107
151
|
|
|
108
|
-
// Operational wrapper: adapter within a timeout
|
|
152
|
+
// Operational wrapper: adapter within a timeout; if it is unreachable, DENY
|
|
153
|
+
// (the default), ESCALATE, or — only if you write it — record-only ALLOW.
|
|
109
154
|
const decision = await enforce({ chain, demand, nowSec }, grantAdapter(), {
|
|
110
155
|
onUnavailable: (err) => alertOps(err),
|
|
111
156
|
});
|
|
@@ -114,8 +159,14 @@ const decision = await enforce({ chain, demand, nowSec }, grantAdapter(), {
|
|
|
114
159
|
- **`evaluateGrant(chain, demand, opts)`** — the pure core.
|
|
115
160
|
- **`grantAdapter()`** — an adapter backed by `evaluateGrant` (the real gate).
|
|
116
161
|
- **`recordOnly`** — the default adapter: always `ALLOW`, never block.
|
|
117
|
-
- **`enforce(decision, adapter, opts)`** — run an adapter with a timeout
|
|
118
|
-
|
|
162
|
+
- **`enforce(decision, adapter, opts)`** — run an adapter with a timeout. When
|
|
163
|
+
it throws or times out, `onUnavailable` is raised and the gate answers per
|
|
164
|
+
`opts.unavailable`: `'deny'` (default, code `adapter_unavailable`),
|
|
165
|
+
`'escalate'`, or `'allow'` (record-only). Until 0.2.0 the fallback was an
|
|
166
|
+
unconditional ALLOW, which made the gate suitable only where enforcement was
|
|
167
|
+
optional — a mandatory boundary that fails open is not a boundary. An org
|
|
168
|
+
with no adapter keeps `recordOnly`; an org that configured one gets it
|
|
169
|
+
enforced even while its policy service is down.
|
|
119
170
|
|
|
120
171
|
The approval bar is enforced in `permits` itself: a demand whose `impact` is at
|
|
121
172
|
or above the chain's effective `approval_at_or_above` refuses with
|
|
@@ -123,6 +174,75 @@ or above the chain's effective `approval_at_or_above` refuses with
|
|
|
123
174
|
meant to see. The gate is the one caller that turns that specific refusal into
|
|
124
175
|
`ESCALATE`. Full contract: [docs/enforcement-gate.md](docs/enforcement-gate.md).
|
|
125
176
|
|
|
177
|
+
## Runtime gating and revocation
|
|
178
|
+
|
|
179
|
+
The gate above answers for the **leaf**: `verifyChain` folds the chain to the
|
|
180
|
+
authority actually in effect — scopes and resources are the leaf's (already
|
|
181
|
+
proved ⊆ every ancestor), the limit is the tightest, the window is the
|
|
182
|
+
intersection (`exp` the earliest, `nbf` the latest) — and `permits` is asked
|
|
183
|
+
of that fold, never of the root. Two consequences a caller can rely on, and
|
|
184
|
+
`gate.test.ts` holds both over random chains: a child can never `ALLOW` what
|
|
185
|
+
its parent `DENY`s, and a child's effective grant is a subset of its parent's
|
|
186
|
+
at every depth. The gate reads no clock; `nowSec` is an argument.
|
|
187
|
+
|
|
188
|
+
Two checks landed with this section. A link may carry **`nbf`** (not-before):
|
|
189
|
+
it is refused `not_yet_valid` before that time, `attenuate` raises a child's
|
|
190
|
+
`nbf` to its parent's the way it caps `exp`, and `verifyChain` refuses one
|
|
191
|
+
injected lower by any other route. And a child **issued before its parent**
|
|
192
|
+
(`iat` earlier than the link that created it) is refused `broken_chain`, at
|
|
193
|
+
build time and at verify time — harmless while one key signs the whole chain,
|
|
194
|
+
fatal once links are independently signed.
|
|
195
|
+
|
|
196
|
+
**The revocation list** — `revocation/1` — is the record `revokedJtis` was
|
|
197
|
+
always meant to come from. Until now a relying party was expected to already
|
|
198
|
+
know what had been revoked, which is the one thing it cannot know about
|
|
199
|
+
another organisation. The list is:
|
|
200
|
+
|
|
201
|
+
- **Append-only.** Every entry carries a `seq` one past the one before; `head`
|
|
202
|
+
is the latest revision; `extendsList(previous, next)` lets a reader that
|
|
203
|
+
cached revision 5 refuse a "revision 7" that rewrote anything in 1..5. A
|
|
204
|
+
mistaken revocation is answered by issuing a new grant, never by editing.
|
|
205
|
+
- **Accountable.** `revoke(list, { jti, by, reason, atSec })` refuses a `by`
|
|
206
|
+
that is not a `person/` or `org/` id (`unaccountable_signer`), a reason
|
|
207
|
+
under 24 characters once trimmed (`reason_too_short`), an id already on
|
|
208
|
+
the list (`already_revoked`), and a time earlier than the entry before
|
|
209
|
+
(`out_of_order`). It returns a new list; the input is never mutated.
|
|
210
|
+
- **Deterministic.** No clock anywhere: `atSec` is injected, `iatSec` on the
|
|
211
|
+
signed form is required, and a verdict names the revision it was computed
|
|
212
|
+
against — `revocationsAsOf` on `authorize` and `evaluateGrant`, `asOf` on
|
|
213
|
+
`verifyChainAgainst` — so "ALLOW as of revision 7" can be restated and an
|
|
214
|
+
auditor recomputes it against the same revision rather than today's.
|
|
215
|
+
`revokedAsOf(list, 9)` on a list that ends at 7 throws rather than answers.
|
|
216
|
+
- **Signed with the assertion key, and nothing else.** `signRevocationList`
|
|
217
|
+
is an EdDSA JWS over the list under `iss`, the same `kid` the JWKS already
|
|
218
|
+
publishes; `verifyRevocationList(jws, { issuer, getKey })` checks it from
|
|
219
|
+
that JWKS and then re-applies every rule above to the payload, so a valid
|
|
220
|
+
signature over a smuggled agent signer is still `null`. A list that does
|
|
221
|
+
not verify is no list — keep the revision you last verified; unread is not
|
|
222
|
+
zero.
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
import { emptyRevocationList, revoke, signRevocationList, verifyRevocationList, authorize } from '@flashyid/sdk';
|
|
226
|
+
|
|
227
|
+
// The issuer, withdrawing one link. A person or an org signs; the reason is said.
|
|
228
|
+
const next = revoke(list, { jti: 'agent-7', by: 'person/michael', reason: 'credential rotated after a laptop was reported lost', atSec });
|
|
229
|
+
if ('ok' in next) throw new Error(next.code); // reason_too_short | unaccountable_signer | already_revoked | out_of_order
|
|
230
|
+
const jws = await signRevocationList(next, { privateKey, kid, iatSec });
|
|
231
|
+
|
|
232
|
+
// A relying party, holding only the JWKS.
|
|
233
|
+
const fetched = await verifyRevocationList(jws, { issuer, getKey });
|
|
234
|
+
const out = await authorize(token, demand, { ...opts, nowSec, revocations: fetched?.list });
|
|
235
|
+
// out.result.code === 'revoked' → detail names the link, who withdrew it, and why
|
|
236
|
+
// out.revocationsAsOf === fetched.list.head
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
A chain containing a revoked link is refused at that link, and everything
|
|
240
|
+
beneath it goes with it; nothing above it is touched (`revocation.test.ts`
|
|
241
|
+
holds it over random chains, every link revoked in turn). Propagation to a
|
|
242
|
+
counterparty holding a *cached* assertion is still the open item on
|
|
243
|
+
`/trust#fm-revoke`: this list is what such a counterparty fetches, and how
|
|
244
|
+
often it fetches is its own freshness decision.
|
|
245
|
+
|
|
126
246
|
## The `flashyid init` command
|
|
127
247
|
|
|
128
248
|
Read an organization's charter and issue the root grants its roles hold — the
|
|
@@ -130,14 +250,77 @@ charter is already the grant, so this is a file read and a mapping, not a
|
|
|
130
250
|
policy language to learn.
|
|
131
251
|
|
|
132
252
|
```sh
|
|
133
|
-
npx flashyid init
|
|
134
|
-
npx flashyid init my-charter.json
|
|
135
|
-
npx flashyid init --json
|
|
253
|
+
npx flashyid init # reads ./flashyos.roles.json, prints a summary
|
|
254
|
+
npx flashyid init my-charter.json # a specific charter file
|
|
255
|
+
npx flashyid init --json # emit the grants as JSON
|
|
256
|
+
npx flashyid init --scopes scopes.json # map capabilities through a registry file
|
|
136
257
|
```
|
|
137
258
|
|
|
138
|
-
Flags: a positional file (or `--file`/`-f`),
|
|
139
|
-
the file is missing/malformed
|
|
140
|
-
|
|
259
|
+
Flags: a positional file (or `--file`/`-f`), `--json`, and `--scopes <file>`.
|
|
260
|
+
Exits non-zero when the file is missing/malformed, the scopes file (if given)
|
|
261
|
+
is missing/malformed, or any role's capability maps to no registered scope —
|
|
262
|
+
an init that would silently drop authority fails loudly instead.
|
|
263
|
+
|
|
264
|
+
### `--scopes <file>` — mapping capabilities to this org's own scopes
|
|
265
|
+
|
|
266
|
+
Without `--scopes`, a role's AAO capabilities (`specify`, `seal`, …) pass
|
|
267
|
+
through unchanged as the grant's `scp`. That's `scopeRegistry` left unset in
|
|
268
|
+
`CharterGrantsOptions` (see `src/grants/fromCharter.ts`) — useful before an
|
|
269
|
+
org has published one, and in tests.
|
|
270
|
+
|
|
271
|
+
`--scopes <file>` points at a JSON object, flat, every value a string:
|
|
272
|
+
|
|
273
|
+
```json
|
|
274
|
+
{ "specify": "rewards:specify", "seal": "ledger:seal" }
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
Every capability any role in the charter carries must appear as a key, or
|
|
278
|
+
that role refuses with `scope_unmapped` and the whole run exits 1 rather than
|
|
279
|
+
issuing a client some of whose capabilities silently vanished. This command
|
|
280
|
+
only reads the file an operator hands it — it ships no registry of its own,
|
|
281
|
+
and does not infer one capability's scope from another's. Populating the
|
|
282
|
+
registry (which `flashyid-spec`'s wire-format scopes a given AAO capability
|
|
283
|
+
should become) is an org's own decision; `docs/rail-grant.md`'s root-trust
|
|
284
|
+
policy — which chain roots a rail will mint a grant for at all — is the
|
|
285
|
+
related decision one layer up, and (unlike this one) it has been ratified:
|
|
286
|
+
estate-named roots only, enforced by `railGrantFromChain`'s required
|
|
287
|
+
`trustedRoots` parameter below.
|
|
288
|
+
|
|
289
|
+
### The `--json` output
|
|
290
|
+
|
|
291
|
+
On a clean run (exit 0) `flashyid init --json` prints **one JSON document and
|
|
292
|
+
nothing else**: an array, one entry per role, in the charter's order.
|
|
293
|
+
|
|
294
|
+
| Key | Is |
|
|
295
|
+
|---|---|
|
|
296
|
+
| `role` | the charter role's name |
|
|
297
|
+
| `holder` | `<slug>/<role>`; `org/<role>` when the charter has no `slug` |
|
|
298
|
+
| `grant` | the root grant chain, an array of links, root-first. `init` issues one link per role |
|
|
299
|
+
|
|
300
|
+
Each link has exactly these keys:
|
|
301
|
+
|
|
302
|
+
| Link key | Is |
|
|
303
|
+
|---|---|
|
|
304
|
+
| `iss` | the charter's `accountableTo`, the human at the root |
|
|
305
|
+
| `sub` | the holder |
|
|
306
|
+
| `scp` | the role's capabilities, deduplicated |
|
|
307
|
+
| `res` | its `worksIn`; `[]` when absent |
|
|
308
|
+
| `lim` | `{ "approval_at_or_above": … }` when the role names `humanApprovalAtOrAbove`, otherwise `{}` |
|
|
309
|
+
| `iat` | issued at, in seconds |
|
|
310
|
+
| `exp` | expiry, in seconds: 90 days after `iat` |
|
|
311
|
+
| `jti` | a random UUID |
|
|
312
|
+
| `par` | `null` for a root: present rather than omitted |
|
|
313
|
+
|
|
314
|
+
`nbf` and `spend_max` are never emitted. The chains pass `verifyChain`.
|
|
315
|
+
|
|
316
|
+
A failure — an unreadable file, invalid JSON, a charter without `accountableTo`
|
|
317
|
+
and `roles[]` — prints a plain-text line beginning `✗` and exits 1, so **check
|
|
318
|
+
the exit code before parsing**. The key set is pinned by
|
|
319
|
+
`src/init/cliJson.test.ts`, which runs the real code over a charter, compares
|
|
320
|
+
the exact key set of every entry and link, and compares the first column of the
|
|
321
|
+
two tables above with the keys the code emitted: a field added to the code, or to
|
|
322
|
+
either table alone, fails it. The descriptions in the second column are prose and
|
|
323
|
+
are not held.
|
|
141
324
|
|
|
142
325
|
## Refusal codes
|
|
143
326
|
|
|
@@ -147,8 +330,9 @@ contract, for relying parties and auditors alike.
|
|
|
147
330
|
| Code | Meaning |
|
|
148
331
|
|---|---|
|
|
149
332
|
| `chain_widened` | a link grants more scope, resource, or limit than its parent |
|
|
150
|
-
| `broken_chain` | a link's issuer is not the holder above it, the chain's leaf holder is not the assertion's subject, or the `del` claim is malformed |
|
|
333
|
+
| `broken_chain` | a link's issuer is not the holder above it, it does not bind its parent, it was issued before its parent, the chain's leaf holder is not the assertion's subject, or the `del` claim is malformed |
|
|
151
334
|
| `expired` | a link is past its expiry at the evaluated time |
|
|
335
|
+
| `not_yet_valid` | a link carries a not-before (`nbf`) the evaluated time has not reached |
|
|
152
336
|
| `revoked` | a link (or one above it) has been revoked |
|
|
153
337
|
| `out_of_mandate` | the action exceeds the chain's effective scope, resource, or spend limit |
|
|
154
338
|
| `approval_required` | in mandate, but at/above the human-approval bar — a named human must co-sign (the gate maps this to `ESCALATE`) |
|
package/dist/cjs/enforce/gate.js
CHANGED
|
@@ -6,6 +6,7 @@ exports.grantAdapter = grantAdapter;
|
|
|
6
6
|
exports.enforce = enforce;
|
|
7
7
|
exports.withTimeout = withTimeout;
|
|
8
8
|
const index_js_1 = require("../grants/index.js");
|
|
9
|
+
const revocation_js_1 = require("../grants/revocation.js");
|
|
9
10
|
/**
|
|
10
11
|
* The gate decision for a signed grant chain against a demanded action. Pure.
|
|
11
12
|
*
|
|
@@ -17,10 +18,21 @@ const index_js_1 = require("../grants/index.js");
|
|
|
17
18
|
* Every other refusal (unsound chain, out of mandate) stays a DENY.
|
|
18
19
|
*/
|
|
19
20
|
function evaluateGrant(chain, demand, opts) {
|
|
20
|
-
|
|
21
|
+
let verified;
|
|
22
|
+
const stamp = {};
|
|
23
|
+
if (opts.revocations) {
|
|
24
|
+
const verdict = (0, revocation_js_1.verifyChainAgainst)(chain, opts.nowSec, opts.revocations, { asOf: opts.asOf, extraRevoked: opts.revokedJtis });
|
|
25
|
+
verified = verdict.result;
|
|
26
|
+
stamp.revocationsAsOf = verdict.asOf;
|
|
27
|
+
}
|
|
28
|
+
else {
|
|
29
|
+
verified = (0, index_js_1.verifyChain)(chain, opts.nowSec, opts.revokedJtis ?? new Set());
|
|
30
|
+
}
|
|
21
31
|
if (!verified.ok) {
|
|
22
|
-
return { action: 'DENY', code: verified.code, reason: verified.detail ?? verified.code };
|
|
32
|
+
return { action: 'DENY', code: verified.code, reason: verified.detail ?? verified.code, ...stamp };
|
|
23
33
|
}
|
|
34
|
+
// The gate decides against the LEAF's effective authority — the intersection
|
|
35
|
+
// down the whole chain, which verifyChain has just folded — never the root's.
|
|
24
36
|
const permitted = (0, index_js_1.permits)(verified, demand);
|
|
25
37
|
if (permitted !== true) {
|
|
26
38
|
if (permitted.code === 'approval_required') {
|
|
@@ -30,11 +42,12 @@ function evaluateGrant(chain, demand, opts) {
|
|
|
30
42
|
action: 'ESCALATE',
|
|
31
43
|
escalateAtOrAbove: verified.lim.approval_at_or_above,
|
|
32
44
|
reason: permitted.detail ?? permitted.code,
|
|
45
|
+
...stamp,
|
|
33
46
|
};
|
|
34
47
|
}
|
|
35
|
-
return { action: 'DENY', code: permitted.code, reason: permitted.detail ?? permitted.code };
|
|
48
|
+
return { action: 'DENY', code: permitted.code, reason: permitted.detail ?? permitted.code, ...stamp };
|
|
36
49
|
}
|
|
37
|
-
return { action: 'ALLOW' };
|
|
50
|
+
return { action: 'ALLOW', ...stamp };
|
|
38
51
|
}
|
|
39
52
|
/**
|
|
40
53
|
* The default: record only, never block. An org with no adapter configured, or
|
|
@@ -47,25 +60,52 @@ exports.recordOnly = {
|
|
|
47
60
|
/** An adapter backed by the grant kernel — the real gate. */
|
|
48
61
|
function grantAdapter() {
|
|
49
62
|
return {
|
|
50
|
-
evaluate: (d) => Promise.resolve(evaluateGrant(d.chain, d.demand, { nowSec: d.nowSec, revokedJtis: d.revokedJtis })),
|
|
63
|
+
evaluate: (d) => Promise.resolve(evaluateGrant(d.chain, d.demand, { nowSec: d.nowSec, revokedJtis: d.revokedJtis, revocations: d.revocations, asOf: d.asOf })),
|
|
51
64
|
};
|
|
52
65
|
}
|
|
53
66
|
/**
|
|
54
67
|
* Run a decision through an adapter with the operational contract: await the
|
|
55
|
-
* adapter up to a timeout; if it throws or times out,
|
|
56
|
-
*
|
|
57
|
-
*
|
|
68
|
+
* adapter up to a timeout; if it throws or times out, raise `onUnavailable`
|
|
69
|
+
* and answer per `opts.unavailable` — DENY unless the caller chose otherwise.
|
|
70
|
+
*
|
|
71
|
+
* Until 0.2.0 this fell back to ALLOW unconditionally ("never block"). That
|
|
72
|
+
* made the gate suitable only where enforcement was optional: a mandatory
|
|
73
|
+
* boundary that fails open is not a boundary. The record-only default for
|
|
74
|
+
* orgs with NO adapter is unchanged — `recordOnly` still answers ALLOW — but
|
|
75
|
+
* an adapter that is configured and unreachable now fails closed by default.
|
|
58
76
|
*/
|
|
59
77
|
async function enforce(decision, adapter, opts = {}) {
|
|
60
78
|
const timeoutMs = opts.timeoutMs ?? 5000;
|
|
79
|
+
const mode = opts.unavailable ?? 'deny';
|
|
61
80
|
try {
|
|
62
|
-
|
|
81
|
+
const answer = await withTimeout(adapter.evaluate(decision), timeoutMs);
|
|
82
|
+
// An adapter that resolves with something that is not one of the three
|
|
83
|
+
// answers — a policy service whose response shape changed, a verdict for
|
|
84
|
+
// another protocol — has not answered. Handing its object back as if it
|
|
85
|
+
// were a verdict lets any caller testing `action !== 'DENY'` proceed, which
|
|
86
|
+
// is the fail-open path with the error message removed. The invariants
|
|
87
|
+
// harness found it: a non-verdict is unavailability, and takes the same
|
|
88
|
+
// fall-back as a throw.
|
|
89
|
+
if (!isVerdict(answer))
|
|
90
|
+
throw new Error(`enforcement adapter returned no verdict (${JSON.stringify(answer) ?? String(answer)})`);
|
|
91
|
+
return answer;
|
|
63
92
|
}
|
|
64
93
|
catch (error) {
|
|
65
94
|
opts.onUnavailable?.(error);
|
|
66
|
-
|
|
95
|
+
const why = error instanceof Error ? error.message : String(error);
|
|
96
|
+
if (mode === 'allow')
|
|
97
|
+
return { action: 'ALLOW', reason: `enforcement adapter unavailable — recorded only (${why})` };
|
|
98
|
+
if (mode === 'escalate') {
|
|
99
|
+
return { action: 'ESCALATE', escalateAtOrAbove: 'LOW', reason: `enforcement adapter unavailable — a human decides (${why})` };
|
|
100
|
+
}
|
|
101
|
+
return { action: 'DENY', code: 'adapter_unavailable', reason: `enforcement adapter unavailable — failing closed (${why})` };
|
|
67
102
|
}
|
|
68
103
|
}
|
|
104
|
+
const ACTIONS = new Set(['ALLOW', 'DENY', 'ESCALATE']);
|
|
105
|
+
/** One of the three answers, and nothing else. */
|
|
106
|
+
function isVerdict(answer) {
|
|
107
|
+
return typeof answer === 'object' && answer !== null && 'action' in answer && typeof answer.action === 'string' && ACTIONS.has(answer.action);
|
|
108
|
+
}
|
|
69
109
|
/** Reject if the promise does not settle within `ms`. */
|
|
70
110
|
function withTimeout(promise, ms) {
|
|
71
111
|
return new Promise((resolve, reject) => {
|
|
@@ -77,7 +77,9 @@ function issueRoot(input) {
|
|
|
77
77
|
lim: input.lim ? { ...input.lim } : {},
|
|
78
78
|
iat: input.iat,
|
|
79
79
|
exp: input.exp,
|
|
80
|
+
...(input.nbf !== undefined ? { nbf: input.nbf } : {}),
|
|
80
81
|
jti: input.jti,
|
|
82
|
+
par: null, // the root binds no parent
|
|
81
83
|
},
|
|
82
84
|
];
|
|
83
85
|
}
|
|
@@ -101,6 +103,15 @@ function attenuate(chain, input) {
|
|
|
101
103
|
return refuse('chain_widened', chain.length, 'resource widened');
|
|
102
104
|
if (!limitWithin(lim, parent.lim))
|
|
103
105
|
return refuse('chain_widened', chain.length, 'limit loosened');
|
|
106
|
+
// A child issued before its parent was not created by it. Harmless while one
|
|
107
|
+
// key signs the whole chain; fatal once links are independently signed, so it
|
|
108
|
+
// is refused at build time as well as at verify time (source audit, 2026-08).
|
|
109
|
+
if (input.iat < parent.iat)
|
|
110
|
+
return refuse('broken_chain', chain.length, 'child issued before its parent');
|
|
111
|
+
// Not-before is the mirror of expiry: exp is capped at the parent's, nbf is
|
|
112
|
+
// raised to the parent's. A chain's window is the intersection of its links'.
|
|
113
|
+
const nbfCandidates = [input.nbf, parent.nbf].filter((x) => x !== undefined);
|
|
114
|
+
const nbf = nbfCandidates.length ? Math.max(...nbfCandidates) : undefined;
|
|
104
115
|
const child = {
|
|
105
116
|
iss: parent.sub, // the parent's holder is this child's issuer
|
|
106
117
|
sub: input.holder,
|
|
@@ -109,24 +120,38 @@ function attenuate(chain, input) {
|
|
|
109
120
|
lim,
|
|
110
121
|
iat: input.iat,
|
|
111
122
|
exp: Math.min(input.exp, parent.exp), // never outlive the parent
|
|
123
|
+
...(nbf !== undefined ? { nbf } : {}),
|
|
112
124
|
jti: input.jti,
|
|
125
|
+
par: parent.jti, // bind this specific parent, so the link cannot be spliced elsewhere
|
|
113
126
|
};
|
|
114
127
|
return [...chain, child];
|
|
115
128
|
}
|
|
116
129
|
/**
|
|
117
130
|
* Verify a chain end to end and resolve the authority in effect, or refuse with
|
|
118
131
|
* the first reason it fails. Enforces continuity (each issuer is the holder
|
|
119
|
-
* above
|
|
120
|
-
*
|
|
121
|
-
*
|
|
122
|
-
*
|
|
132
|
+
* above AND each link binds its specific parent by `par`), the narrowing
|
|
133
|
+
* invariant at every hop, expiry at `nowSec`, and (optionally) revocation.
|
|
134
|
+
* Independent of how the chain was built — a chain that widened, or was spliced
|
|
135
|
+
* together from links of different chains, by any route is caught here, which
|
|
136
|
+
* is why attenuate's guard is not the only line of defense.
|
|
137
|
+
*
|
|
138
|
+
* This is a check over the chain's STRUCTURE, not its signatures: it proves the
|
|
139
|
+
* links narrow and link to one another, not that an issuer signed them. A
|
|
140
|
+
* relying party verifies the signature separately — `verifyAssertion` /
|
|
141
|
+
* `authorize` in the SDK do both, and are what a consumer should call. Running
|
|
142
|
+
* `verifyChain` alone on wire data proves narrowing, never authenticity.
|
|
123
143
|
*/
|
|
124
144
|
function verifyChain(chain, nowSec, revokedJtis = new Set()) {
|
|
125
145
|
const first = chain[0];
|
|
126
146
|
if (!first)
|
|
127
147
|
return refuse('empty_chain');
|
|
148
|
+
// The root binds no parent; a root that names one is malformed (a spliced
|
|
149
|
+
// sub-chain presented as if it were whole).
|
|
150
|
+
if (first.par !== null)
|
|
151
|
+
return refuse('broken_chain', 0, 'root link must not bind a parent');
|
|
128
152
|
let effLim = { ...first.lim };
|
|
129
153
|
let effExp = first.exp;
|
|
154
|
+
let effNbf = first.nbf;
|
|
130
155
|
for (let i = 0; i < chain.length; i++) {
|
|
131
156
|
const link = chain[i];
|
|
132
157
|
if (!link)
|
|
@@ -138,12 +163,26 @@ function verifyChain(chain, nowSec, revokedJtis = new Set()) {
|
|
|
138
163
|
return refuse('revoked', i);
|
|
139
164
|
if (link.exp <= nowSec)
|
|
140
165
|
return refuse('expired', i);
|
|
166
|
+
// A link is in force from its not-before, when it carries one. Checked per
|
|
167
|
+
// link, so the effective window is the intersection: the latest nbf and the
|
|
168
|
+
// earliest exp across the chain.
|
|
169
|
+
if (link.nbf !== undefined && nowSec < link.nbf)
|
|
170
|
+
return refuse('not_yet_valid', i);
|
|
141
171
|
if (i > 0) {
|
|
142
172
|
const parent = chain[i - 1];
|
|
143
173
|
if (!parent)
|
|
144
174
|
return refuse('broken_chain', i);
|
|
145
175
|
if (link.iss !== parent.sub)
|
|
146
176
|
return refuse('broken_chain', i, 'issuer is not the holder above');
|
|
177
|
+
// A child dated before its parent was not created by it. `attenuate`
|
|
178
|
+
// refuses to build one; this refuses one that arrived by any other route.
|
|
179
|
+
if (link.iat < parent.iat)
|
|
180
|
+
return refuse('broken_chain', i, 'link issued before its parent');
|
|
181
|
+
// Parent binding: the link must name its exact parent, not merely some
|
|
182
|
+
// link with a matching holder. This is what refuses a splice — a leaf
|
|
183
|
+
// lifted from one chain and dropped under a same-holder parent in another.
|
|
184
|
+
if (link.par !== parent.jti)
|
|
185
|
+
return refuse('broken_chain', i, 'link does not bind its stated parent (splice)');
|
|
147
186
|
if (!isSubset(link.scp, parent.scp))
|
|
148
187
|
return refuse('chain_widened', i, 'scope widened');
|
|
149
188
|
if (!isSubset(link.res, parent.res))
|
|
@@ -152,6 +191,8 @@ function verifyChain(chain, nowSec, revokedJtis = new Set()) {
|
|
|
152
191
|
return refuse('chain_widened', i, 'limit loosened');
|
|
153
192
|
effLim = tightestLimit(effLim, link.lim);
|
|
154
193
|
effExp = Math.min(effExp, link.exp);
|
|
194
|
+
if (link.nbf !== undefined)
|
|
195
|
+
effNbf = effNbf === undefined ? link.nbf : Math.max(effNbf, link.nbf);
|
|
155
196
|
}
|
|
156
197
|
}
|
|
157
198
|
const leaf = chain[chain.length - 1];
|
|
@@ -165,6 +206,7 @@ function verifyChain(chain, nowSec, revokedJtis = new Set()) {
|
|
|
165
206
|
res: [...leaf.res],
|
|
166
207
|
lim: effLim,
|
|
167
208
|
exp: effExp,
|
|
209
|
+
...(effNbf !== undefined ? { nbf: effNbf } : {}),
|
|
168
210
|
chain: chain.map((l) => l.jti),
|
|
169
211
|
};
|
|
170
212
|
return effective;
|
package/dist/cjs/grants/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.grantFromCharterRole = exports.rootsWithin = exports.permits = exports.verifyChain = exports.attenuate = exports.issueRoot = void 0;
|
|
17
|
+
exports.grantFromCharterRole = 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.rootsWithin = exports.permits = exports.verifyChain = exports.attenuate = exports.issueRoot = void 0;
|
|
18
18
|
/**
|
|
19
19
|
* @flashyid/grants — the delegated-authority grant kernel.
|
|
20
20
|
*
|
|
@@ -33,5 +33,17 @@ Object.defineProperty(exports, "attenuate", { enumerable: true, get: function ()
|
|
|
33
33
|
Object.defineProperty(exports, "verifyChain", { enumerable: true, get: function () { return grants_js_1.verifyChain; } });
|
|
34
34
|
Object.defineProperty(exports, "permits", { enumerable: true, get: function () { return grants_js_1.permits; } });
|
|
35
35
|
Object.defineProperty(exports, "rootsWithin", { enumerable: true, get: function () { return grants_js_1.rootsWithin; } });
|
|
36
|
+
var revocation_js_1 = require("./revocation.js");
|
|
37
|
+
Object.defineProperty(exports, "emptyRevocationList", { enumerable: true, get: function () { return revocation_js_1.emptyRevocationList; } });
|
|
38
|
+
Object.defineProperty(exports, "revoke", { enumerable: true, get: function () { return revocation_js_1.revoke; } });
|
|
39
|
+
Object.defineProperty(exports, "revokedAsOf", { enumerable: true, get: function () { return revocation_js_1.revokedAsOf; } });
|
|
40
|
+
Object.defineProperty(exports, "revocationOf", { enumerable: true, get: function () { return revocation_js_1.revocationOf; } });
|
|
41
|
+
Object.defineProperty(exports, "extendsList", { enumerable: true, get: function () { return revocation_js_1.extendsList; } });
|
|
42
|
+
Object.defineProperty(exports, "validateRevocationList", { enumerable: true, get: function () { return revocation_js_1.validateRevocationList; } });
|
|
43
|
+
Object.defineProperty(exports, "verifyChainAgainst", { enumerable: true, get: function () { return revocation_js_1.verifyChainAgainst; } });
|
|
44
|
+
Object.defineProperty(exports, "isAccountableSigner", { enumerable: true, get: function () { return revocation_js_1.isAccountableSigner; } });
|
|
45
|
+
Object.defineProperty(exports, "REVOCATION_LIST_VERSION", { enumerable: true, get: function () { return revocation_js_1.REVOCATION_LIST_VERSION; } });
|
|
46
|
+
Object.defineProperty(exports, "REVOCATION_REASON_MIN", { enumerable: true, get: function () { return revocation_js_1.REVOCATION_REASON_MIN; } });
|
|
47
|
+
Object.defineProperty(exports, "REVOCATION_SIGNER_PREFIXES", { enumerable: true, get: function () { return revocation_js_1.REVOCATION_SIGNER_PREFIXES; } });
|
|
36
48
|
var fromCharter_js_1 = require("./fromCharter.js");
|
|
37
49
|
Object.defineProperty(exports, "grantFromCharterRole", { enumerable: true, get: function () { return fromCharter_js_1.grantFromCharterRole; } });
|