@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 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, record-only fallback + alert.
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 and
118
- fall back to record-only (raising `onUnavailable`) when it is unreachable.
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 # reads ./flashyos.roles.json, prints a summary
134
- npx flashyid init my-charter.json # a specific charter file
135
- npx flashyid init --json # emit the grants as 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`), and `--json`. Exits non-zero when
139
- the file is missing/malformed or any role's capability maps to no registered
140
- scope — an init that would silently drop authority fails loudly instead.
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`) |
@@ -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
- const verified = (0, index_js_1.verifyChain)(chain, opts.nowSec, opts.revokedJtis ?? new Set());
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, fall back to record-only
56
- * ALLOW and raise `onUnavailable`. Preserves "never block" for everyone, while
57
- * giving an adapter-configured org a real gate.
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
- return await withTimeout(adapter.evaluate(decision), timeoutMs);
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
- return { action: 'ALLOW', reason: 'enforcement adapter unavailable — recorded only' };
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), 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.
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;
@@ -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; } });