@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.
Files changed (40) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +171 -0
  3. package/dist/cjs/enforce/gate.js +81 -0
  4. package/dist/cjs/grants/fromCharter.js +36 -0
  5. package/dist/cjs/grants/grants.js +227 -0
  6. package/dist/cjs/grants/index.js +37 -0
  7. package/dist/cjs/grants/subject.js +107 -0
  8. package/dist/cjs/grants/types.js +24 -0
  9. package/dist/cjs/index.js +49 -0
  10. package/dist/cjs/init/charterGrants.js +83 -0
  11. package/dist/cjs/package.json +1 -0
  12. package/dist/cjs/sdk/index.js +27 -0
  13. package/dist/cjs/sdk/sign.js +22 -0
  14. package/dist/cjs/sdk/verify.js +138 -0
  15. package/dist/enforce/gate.d.ts +88 -0
  16. package/dist/enforce/gate.js +74 -0
  17. package/dist/grants/fromCharter.d.ts +43 -0
  18. package/dist/grants/fromCharter.js +33 -0
  19. package/dist/grants/grants.d.ts +93 -0
  20. package/dist/grants/grants.js +220 -0
  21. package/dist/grants/index.d.ts +16 -0
  22. package/dist/grants/index.js +14 -0
  23. package/dist/grants/subject.d.ts +78 -0
  24. package/dist/grants/subject.js +99 -0
  25. package/dist/grants/types.d.ts +83 -0
  26. package/dist/grants/types.js +20 -0
  27. package/dist/index.d.ts +18 -0
  28. package/dist/index.js +18 -0
  29. package/dist/init/charterGrants.d.ts +96 -0
  30. package/dist/init/charterGrants.js +78 -0
  31. package/dist/init/cli.d.ts +23 -0
  32. package/dist/init/cli.js +102 -0
  33. package/dist/sdk/index.d.ts +16 -0
  34. package/dist/sdk/index.js +13 -0
  35. package/dist/sdk/sign.d.ts +42 -0
  36. package/dist/sdk/sign.js +19 -0
  37. package/dist/sdk/verify.d.ts +85 -0
  38. package/dist/sdk/verify.js +134 -0
  39. package/docs/enforcement-gate.md +56 -0
  40. package/package.json +63 -0
@@ -0,0 +1,138 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.verifyAssertion = verifyAssertion;
4
+ exports.authorize = authorize;
5
+ const jose_1 = require("jose");
6
+ const grants_js_1 = require("../grants/grants.js");
7
+ const types_js_1 = require("../grants/types.js");
8
+ function isStringArray(v) {
9
+ return Array.isArray(v) && v.every((x) => typeof x === 'string');
10
+ }
11
+ function isLimit(v) {
12
+ if (typeof v !== 'object' || v === null || Array.isArray(v))
13
+ return false;
14
+ const lim = v;
15
+ if (lim.approval_at_or_above !== undefined && !types_js_1.IMPACT_ORDER.includes(lim.approval_at_or_above)) {
16
+ return false;
17
+ }
18
+ if (lim.spend_max !== undefined && typeof lim.spend_max !== 'number')
19
+ return false;
20
+ return true;
21
+ }
22
+ function isGrantLink(v) {
23
+ if (typeof v !== 'object' || v === null)
24
+ return false;
25
+ const l = v;
26
+ return (typeof l.iss === 'string' &&
27
+ typeof l.sub === 'string' &&
28
+ isStringArray(l.scp) &&
29
+ isStringArray(l.res) &&
30
+ isLimit(l.lim) &&
31
+ typeof l.iat === 'number' &&
32
+ typeof l.exp === 'number' &&
33
+ typeof l.jti === 'string');
34
+ }
35
+ /**
36
+ * A `del` claim is attacker-adjacent wire data: it arrives inside a signed
37
+ * token, but nothing about the signature guarantees the claim has the shape
38
+ * the grant kernel assumes. Validate it before it is ever typed as a chain.
39
+ */
40
+ function isGrantChain(v) {
41
+ return Array.isArray(v) && v.every(isGrantLink);
42
+ }
43
+ const remoteKeySets = new Map();
44
+ function remoteKeyFor(issuer) {
45
+ const existing = remoteKeySets.get(issuer);
46
+ if (existing)
47
+ return existing;
48
+ const set = (0, jose_1.createRemoteJWKSet)(new URL(`${issuer.replace(/\/+$/, '')}/.well-known/jwks.json`));
49
+ remoteKeySets.set(issuer, set);
50
+ return set;
51
+ }
52
+ /**
53
+ * Verify an assertion's signature and standard claims. Returns the identity and
54
+ * any delegation it carries, or null if the token is missing, malformed,
55
+ * expired, wrong-issuer, wrong-audience, or fails signature verification. Never
56
+ * throws — a bad token is a null, which a relying party turns into a 401.
57
+ *
58
+ * The `del` claim is shape-validated before it is typed as a chain: a `del`
59
+ * that is present but not a well-formed GrantChain is left off the returned
60
+ * assertion (`del: undefined`) rather than cast and trusted. The raw claim
61
+ * stays visible in `claims`, so `authorize` can distinguish "no delegation"
62
+ * from "malformed delegation" and refuse the latter explicitly.
63
+ */
64
+ async function verifyAssertion(token, opts) {
65
+ if (!token)
66
+ return null;
67
+ const key = opts.getKey ?? remoteKeyFor(opts.issuer);
68
+ try {
69
+ const { payload } = await (0, jose_1.jwtVerify)(token, key, {
70
+ issuer: opts.issuer,
71
+ audience: opts.audience,
72
+ });
73
+ if (typeof payload.sub !== 'string' || !payload.sub)
74
+ return null;
75
+ const del = isGrantChain(payload.del) ? payload.del : undefined;
76
+ return { sub: payload.sub, del, claims: payload };
77
+ }
78
+ catch {
79
+ return null;
80
+ }
81
+ }
82
+ /**
83
+ * The full relying-party check: verify the assertion, then verify the delegation
84
+ * it carries authorizes a specific action. One call, one boolean-ish answer,
85
+ * with a specific refusal when it fails.
86
+ *
87
+ * Returns the effective grant on success. Returns null when the assertion itself
88
+ * doesn't verify (a 401 for the relying party). Returns a refusal when the
89
+ * assertion is genuine but its delegation is malformed, unsound, not held by
90
+ * the assertion's subject, or doesn't permit the demand (a 403 — and the
91
+ * refusal code says which).
92
+ *
93
+ * Two checks beyond the chain's own soundness:
94
+ * - The chain's leaf holder must be the assertion's `sub` — an assertion for
95
+ * A carrying a chain delegated to B is refused (`broken_chain`), since the
96
+ * acting principal would not be the one the authority rests with.
97
+ * - The human-approval bar is enforced by `permits`: a demand whose `impact`
98
+ * is at or above the chain's effective `approval_at_or_above` is refused
99
+ * with `approval_required`, never silently allowed. A relying party that
100
+ * can route to a human for a co-signature should use the enforcement
101
+ * gate's `evaluateGrant`, which turns that same refusal into ESCALATE.
102
+ */
103
+ async function authorize(token, demand, opts) {
104
+ const assertion = await verifyAssertion(token, opts);
105
+ if (!assertion)
106
+ return null;
107
+ if (!assertion.del) {
108
+ // verifyAssertion drops a `del` that fails shape validation; the raw claim
109
+ // tells malformed apart from absent, and each refuses with its own reason.
110
+ if (assertion.claims.del !== undefined) {
111
+ return { assertion, result: { ok: false, code: 'broken_chain', detail: 'delegation is not a well-formed grant chain' } };
112
+ }
113
+ return { assertion, result: { ok: false, code: 'empty_chain', detail: 'assertion carries no delegation' } };
114
+ }
115
+ const verified = (0, grants_js_1.verifyChain)(assertion.del, opts.nowSec, opts.revokedJtis ?? new Set());
116
+ if (!verified.ok)
117
+ return { assertion, result: verified };
118
+ if (verified.holder !== assertion.sub) {
119
+ return {
120
+ assertion,
121
+ result: {
122
+ ok: false,
123
+ code: 'broken_chain',
124
+ detail: `chain leaf holder ${verified.holder} is not the assertion subject ${assertion.sub}`,
125
+ },
126
+ };
127
+ }
128
+ // The mesh binding: a sound, subject-held chain still has to root where this
129
+ // party agreed. Checked before permits so an untrusted root cannot be masked
130
+ // by also lacking the demanded scope.
131
+ if (opts.trustedRoots !== undefined) {
132
+ const rooted = (0, grants_js_1.rootsWithin)(verified, opts.trustedRoots);
133
+ if (rooted !== true)
134
+ return { assertion, result: rooted };
135
+ }
136
+ const p = (0, grants_js_1.permits)(verified, demand);
137
+ return { assertion, result: p === true ? verified : p };
138
+ }
@@ -0,0 +1,88 @@
1
+ import { type Demand } from '../grants/index.js';
2
+ import { type GrantChain, type Impact, type RefusalCode } from '../grants/types.js';
3
+ /**
4
+ * The enforcement gate.
5
+ *
6
+ * A governance layer that only *records* has a liability ceiling: enterprises
7
+ * need a decision that can *gate*. The delegated-authority grant kernel already
8
+ * answers the hard question — does a signed, unrevoked, in-mandate grant permit
9
+ * this action? — so the gate is not a new policy engine. It is a thin mapping
10
+ * of `verifyChain` + `permits` onto the three answers a caller can act on:
11
+ *
12
+ * ALLOW — the grant permits it, below the human-approval bar. Proceed.
13
+ * ESCALATE — permitted, but at or above the bar a named human must co-sign.
14
+ * DENY — the chain is unsound (expired, revoked, widened, broken) or the
15
+ * action is out of mandate (scope, resource, or spend exceeded).
16
+ *
17
+ * `evaluateGrant` is pure — no clock, no I/O — so the same decision is reached
18
+ * by the issuer, a relying party, and an auditor. The async `enforce` wrapper
19
+ * adds only the operational contract from the institutional brief: try an
20
+ * adapter within a timeout, and if it is unreachable fall back to record-only
21
+ * (never block an agent on an unavailable gate) while raising an alert.
22
+ */
23
+ export type EnforcementAction = 'ALLOW' | 'DENY' | 'ESCALATE';
24
+ export interface EnforcementResult {
25
+ action: EnforcementAction;
26
+ /** Human-readable rationale. */
27
+ reason?: string;
28
+ /** For DENY, the grant kernel's refusal code — the auditable "why". */
29
+ code?: RefusalCode;
30
+ /** For ESCALATE, the impact bar at or above which a human must co-sign. */
31
+ escalateAtOrAbove?: Impact;
32
+ }
33
+ export interface EvaluateOptions {
34
+ /** Seconds since epoch to evaluate expiry against. */
35
+ nowSec: number;
36
+ /** Revoked grant ids — a revoked link, or any ancestor, kills the chain. */
37
+ revokedJtis?: ReadonlySet<string>;
38
+ }
39
+ /**
40
+ * The gate decision for a signed grant chain against a demanded action. Pure.
41
+ *
42
+ * The human-approval bar is enforced inside `permits` itself (refusal code
43
+ * `approval_required`), so no call path can silently allow a CRITICAL action a
44
+ * human was meant to see. The gate is the one caller that can route to a
45
+ * human, so it maps that specific refusal — and only that one — to ESCALATE:
46
+ * the action *is* within mandate, it just needs a named human's co-signature.
47
+ * Every other refusal (unsound chain, out of mandate) stays a DENY.
48
+ */
49
+ export declare function evaluateGrant(chain: GrantChain, demand: Demand, opts: EvaluateOptions): EnforcementResult;
50
+ /**
51
+ * The adapter an enterprise registers to gate decisions. `evaluate` returns the
52
+ * action to take. An adapter may reach out to its own policy service; the gate
53
+ * only cares about the answer.
54
+ */
55
+ export interface EnforcementAdapter {
56
+ evaluate(decision: DecisionInput): Promise<EnforcementResult>;
57
+ }
58
+ /** What the gate hands an adapter: the grant to check and the action demanded. */
59
+ export interface DecisionInput {
60
+ chain: GrantChain;
61
+ demand: Demand;
62
+ nowSec: number;
63
+ revokedJtis?: ReadonlySet<string>;
64
+ }
65
+ /**
66
+ * The default: record only, never block. An org with no adapter configured, or
67
+ * whose adapter is unreachable, must not have its agents halted — the mesh is
68
+ * an audit trail, not a single point of failure. Always ALLOW.
69
+ */
70
+ export declare const recordOnly: EnforcementAdapter;
71
+ /** An adapter backed by the grant kernel — the real gate. */
72
+ export declare function grantAdapter(): EnforcementAdapter;
73
+ export interface EnforceOptions {
74
+ /** Milliseconds to wait for the adapter before falling back. Default 5000. */
75
+ timeoutMs?: number;
76
+ /** Raised when the adapter is unreachable and the gate falls back to allow —
77
+ * the CRITICAL alert an operator wires to their monitoring. */
78
+ onUnavailable?: (error: unknown) => void;
79
+ }
80
+ /**
81
+ * Run a decision through an adapter with the operational contract: await the
82
+ * adapter up to a timeout; if it throws or times out, fall back to record-only
83
+ * ALLOW and raise `onUnavailable`. Preserves "never block" for everyone, while
84
+ * giving an adapter-configured org a real gate.
85
+ */
86
+ export declare function enforce(decision: DecisionInput, adapter: EnforcementAdapter, opts?: EnforceOptions): Promise<EnforcementResult>;
87
+ /** Reject if the promise does not settle within `ms`. */
88
+ export declare function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T>;
@@ -0,0 +1,74 @@
1
+ import { verifyChain, permits } from '../grants/index.js';
2
+ /**
3
+ * The gate decision for a signed grant chain against a demanded action. Pure.
4
+ *
5
+ * The human-approval bar is enforced inside `permits` itself (refusal code
6
+ * `approval_required`), so no call path can silently allow a CRITICAL action a
7
+ * human was meant to see. The gate is the one caller that can route to a
8
+ * human, so it maps that specific refusal — and only that one — to ESCALATE:
9
+ * the action *is* within mandate, it just needs a named human's co-signature.
10
+ * Every other refusal (unsound chain, out of mandate) stays a DENY.
11
+ */
12
+ export function evaluateGrant(chain, demand, opts) {
13
+ const verified = verifyChain(chain, opts.nowSec, opts.revokedJtis ?? new Set());
14
+ if (!verified.ok) {
15
+ return { action: 'DENY', code: verified.code, reason: verified.detail ?? verified.code };
16
+ }
17
+ const permitted = permits(verified, demand);
18
+ if (permitted !== true) {
19
+ if (permitted.code === 'approval_required') {
20
+ // Permitted, but at or above the bar a named human must co-sign —
21
+ // escalate rather than deny (or silently allow).
22
+ return {
23
+ action: 'ESCALATE',
24
+ escalateAtOrAbove: verified.lim.approval_at_or_above,
25
+ reason: permitted.detail ?? permitted.code,
26
+ };
27
+ }
28
+ return { action: 'DENY', code: permitted.code, reason: permitted.detail ?? permitted.code };
29
+ }
30
+ return { action: 'ALLOW' };
31
+ }
32
+ /**
33
+ * The default: record only, never block. An org with no adapter configured, or
34
+ * whose adapter is unreachable, must not have its agents halted — the mesh is
35
+ * an audit trail, not a single point of failure. Always ALLOW.
36
+ */
37
+ export const recordOnly = {
38
+ evaluate: () => Promise.resolve({ action: 'ALLOW', reason: 'record-only: no enforcement adapter' }),
39
+ };
40
+ /** An adapter backed by the grant kernel — the real gate. */
41
+ export function grantAdapter() {
42
+ return {
43
+ evaluate: (d) => Promise.resolve(evaluateGrant(d.chain, d.demand, { nowSec: d.nowSec, revokedJtis: d.revokedJtis })),
44
+ };
45
+ }
46
+ /**
47
+ * Run a decision through an adapter with the operational contract: await the
48
+ * adapter up to a timeout; if it throws or times out, fall back to record-only
49
+ * ALLOW and raise `onUnavailable`. Preserves "never block" for everyone, while
50
+ * giving an adapter-configured org a real gate.
51
+ */
52
+ export async function enforce(decision, adapter, opts = {}) {
53
+ const timeoutMs = opts.timeoutMs ?? 5000;
54
+ try {
55
+ return await withTimeout(adapter.evaluate(decision), timeoutMs);
56
+ }
57
+ catch (error) {
58
+ opts.onUnavailable?.(error);
59
+ return { action: 'ALLOW', reason: 'enforcement adapter unavailable — recorded only' };
60
+ }
61
+ }
62
+ /** Reject if the promise does not settle within `ms`. */
63
+ export function withTimeout(promise, ms) {
64
+ return new Promise((resolve, reject) => {
65
+ const timer = setTimeout(() => reject(new Error(`enforcement adapter timed out after ${ms}ms`)), ms);
66
+ promise.then((value) => {
67
+ clearTimeout(timer);
68
+ resolve(value);
69
+ }, (error) => {
70
+ clearTimeout(timer);
71
+ reject(error instanceof Error ? error : new Error(String(error)));
72
+ });
73
+ });
74
+ }
@@ -0,0 +1,43 @@
1
+ import { type GrantChain, type Impact, type Refusal } from './types.js';
2
+ /**
3
+ * The charter is already the grant.
4
+ *
5
+ * An AAO charter role carries exactly the fields a delegated-authority grant
6
+ * needs — nobody has to invent a policy language:
7
+ *
8
+ * capabilities → scp (the verbs this role may perform)
9
+ * worksIn → res (the repositories it may act on)
10
+ * humanApprovalAtOrAbove → lim.approval_at_or_above
11
+ * accountableTo (charter) → the human at the root of the chain
12
+ *
13
+ * This maps that role onto a root grant. It is pure — the caller supplies the
14
+ * time and jti — so a `flashyid init` command, a test, and an audit script all
15
+ * produce the same grant from the same charter.
16
+ */
17
+ /** The subset of an AAO role this mapping reads (structurally typed, no @flashyos/aao dependency). */
18
+ export interface CharterRoleInput {
19
+ name: string;
20
+ capabilities: string[];
21
+ humanApprovalAtOrAbove?: Impact;
22
+ worksIn?: string[];
23
+ }
24
+ export interface FromCharterInput {
25
+ /** The charter's accountableTo — the human at the root of every chain. */
26
+ accountableTo: string;
27
+ role: CharterRoleInput;
28
+ /** Who holds the grant — typically the client/agent id for the role. */
29
+ holder: string;
30
+ iat: number;
31
+ exp: number;
32
+ jti: string;
33
+ /**
34
+ * Optional capability→scope registry. When supplied, a capability that maps
35
+ * to nothing is *refused* (`scope_unmapped`) rather than passed through — the
36
+ * spec's rule that an unmapped capability is refused, not guessed. When
37
+ * omitted, capabilities pass through as scopes unchanged (useful in tests and
38
+ * before a registry is published).
39
+ */
40
+ scopeRegistry?: Readonly<Record<string, string>>;
41
+ }
42
+ /** Map a chartered role to a root grant, or refuse if a capability is unmapped. */
43
+ export declare function grantFromCharterRole(input: FromCharterInput): GrantChain | Refusal;
@@ -0,0 +1,33 @@
1
+ import { issueRoot } from './grants.js';
2
+ /** Map a chartered role to a root grant, or refuse if a capability is unmapped. */
3
+ export function grantFromCharterRole(input) {
4
+ const { role, scopeRegistry } = input;
5
+ let scp;
6
+ if (scopeRegistry) {
7
+ const mapped = [];
8
+ for (const cap of role.capabilities) {
9
+ const scope = scopeRegistry[cap];
10
+ if (scope === undefined) {
11
+ return { ok: false, code: 'scope_unmapped', detail: `capability "${cap}" maps to no registered scope` };
12
+ }
13
+ mapped.push(scope);
14
+ }
15
+ scp = [...new Set(mapped)];
16
+ }
17
+ else {
18
+ scp = [...new Set(role.capabilities)];
19
+ }
20
+ const lim = {};
21
+ if (role.humanApprovalAtOrAbove !== undefined)
22
+ lim.approval_at_or_above = role.humanApprovalAtOrAbove;
23
+ return issueRoot({
24
+ rootHuman: input.accountableTo,
25
+ holder: input.holder,
26
+ scp,
27
+ res: role.worksIn ? [...role.worksIn] : [],
28
+ lim,
29
+ iat: input.iat,
30
+ exp: input.exp,
31
+ jti: input.jti,
32
+ });
33
+ }
@@ -0,0 +1,93 @@
1
+ import { type GrantChain, type Limit, type Impact, type GrantResult, type Refusal, type EffectiveGrant } from './types.js';
2
+ export interface IssueRootInput {
3
+ /** The accountable human — the root of every chain (charter accountableTo). */
4
+ rootHuman: string;
5
+ /** Who the root grant is held by (often the same human, or a client/org). */
6
+ holder: string;
7
+ scp: string[];
8
+ res: string[];
9
+ lim?: Limit;
10
+ iat: number;
11
+ exp: number;
12
+ jti: string;
13
+ }
14
+ /** Mint the root link of a chain, issued from the accountable human. */
15
+ export declare function issueRoot(input: IssueRootInput): GrantChain;
16
+ export interface AttenuateInput {
17
+ /** The new holder this link is delegated to. */
18
+ holder: string;
19
+ /** Scopes for the child — must be ⊆ the parent's. Defaults to the parent's. */
20
+ scp?: string[];
21
+ /** Resources for the child — must be ⊆ the parent's. Defaults to the parent's. */
22
+ res?: string[];
23
+ /** Limit for the child — must be no looser than the parent's. Defaults to the parent's. */
24
+ lim?: Limit;
25
+ iat: number;
26
+ /** Child expiry. Capped at the parent's (a child never outlives its parent). */
27
+ exp: number;
28
+ jti: string;
29
+ }
30
+ /**
31
+ * Append an attenuated link. Refuses (`chain_widened`) rather than silently
32
+ * clamping when the requested child exceeds the parent — a caller asking for
33
+ * more than it holds is a bug to surface, not to paper over. Expiry is the one
34
+ * field capped rather than refused: a child asking to outlive its parent gets
35
+ * the parent's expiry, since the effective expiry would be the min anyway.
36
+ */
37
+ export declare function attenuate(chain: GrantChain, input: AttenuateInput): GrantChain | Refusal;
38
+ /**
39
+ * Verify a chain end to end and resolve the authority in effect, or refuse with
40
+ * the first reason it fails. Enforces continuity (each issuer is the holder
41
+ * above), the narrowing invariant at every hop, expiry at `nowSec`, and
42
+ * (optionally) revocation. Independent of how the chain was built — a chain
43
+ * that widened by any route is caught here, which is why attenuate's guard is
44
+ * not the only line of defense.
45
+ */
46
+ export declare function verifyChain(chain: GrantChain, nowSec: number, revokedJtis?: ReadonlySet<string>): GrantResult;
47
+ export interface Demand {
48
+ /** The scope the action requires. */
49
+ scope: string;
50
+ /** The resource the action touches. */
51
+ resource?: string;
52
+ /** The value the action moves, in minor units. */
53
+ amount?: number;
54
+ /** The severity of the action. */
55
+ impact?: Impact;
56
+ }
57
+ /**
58
+ * Does a verified chain actually authorize a specific action? Separated from
59
+ * verifyChain so the two questions — "is this chain sound?" and "does it permit
60
+ * *this*?" — refuse with distinct reasons (`out_of_mandate` here, structural
61
+ * codes there).
62
+ *
63
+ * The human-approval bar is enforced here, not merely read: a demand whose
64
+ * `impact` is at or above the chain's effective `approval_at_or_above` is
65
+ * refused with `approval_required` — never a silent `true` — because this
66
+ * function cannot see whether a human co-signed. `permits` returning `true`
67
+ * therefore means "proceed without a co-signature". A caller that *can* route
68
+ * to a human (the enforcement gate's `evaluateGrant`) treats the
69
+ * `approval_required` refusal as ESCALATE rather than DENY; a caller that
70
+ * cannot (`authorize`) surfaces it as a refusal. A demand with no `impact`
71
+ * declared is treated as below the bar — impact classification is the
72
+ * caller's contract with its action vocabulary.
73
+ */
74
+ export declare function permits(effective: EffectiveGrant, demand: Demand): true | Refusal;
75
+ /**
76
+ * Does a sound chain root at a principal this relying party actually accepts?
77
+ *
78
+ * Chain soundness (verifyChain) proves a chain only ever narrows and is held by
79
+ * whoever it says — but a sound chain can root at *any* human. On the mesh that
80
+ * is not enough: an agent signing in at org B with a genuine Flashy ID assertion
81
+ * could carry a chain rooted at any accountable human anywhere. A relying party
82
+ * has to pin the roots it will honour, or "verified" quietly means "verified to
83
+ * belong to someone, somewhere". This is that pin, kept separate from permits so
84
+ * an untrusted root refuses with its own reason rather than looking like an
85
+ * out-of-mandate scope.
86
+ *
87
+ * `trustedRoots` is the set of `iss` values (the accountable humans, or org ids)
88
+ * whose authority this party accepts — typically the `accountableTo` of every
89
+ * AAO charter it federates with. An empty set trusts nobody and refuses every
90
+ * chain, which is the safe direction: a relying party that forgot to configure
91
+ * its roots rejects rather than admits.
92
+ */
93
+ export declare function rootsWithin(effective: EffectiveGrant, trustedRoots: Iterable<string>): true | Refusal;