@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,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;
|