@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/dist/init/cli.d.ts
CHANGED
|
@@ -4,6 +4,14 @@ export interface InitArgs {
|
|
|
4
4
|
file: string;
|
|
5
5
|
/** Emit the grants as JSON instead of the human summary. */
|
|
6
6
|
json: boolean;
|
|
7
|
+
/**
|
|
8
|
+
* Optional capability→scope registry file (JSON object of string → string).
|
|
9
|
+
* When given, a role capability that maps to nothing in it refuses the run
|
|
10
|
+
* (`scope_unmapped`) instead of passing the capability through unchanged —
|
|
11
|
+
* see CharterGrantsOptions.scopeRegistry. This flag only supplies the file;
|
|
12
|
+
* it invents no mapping of its own.
|
|
13
|
+
*/
|
|
14
|
+
scopesFile?: string;
|
|
7
15
|
}
|
|
8
16
|
export declare function parseInitArgs(argv: readonly string[]): InitArgs;
|
|
9
17
|
export interface InitDeps {
|
package/dist/init/cli.js
CHANGED
|
@@ -13,11 +13,19 @@ import { grantsFromCharter, summarizeGrants } from './charterGrants.js';
|
|
|
13
13
|
* network-bearing step — registering the resulting client with the live
|
|
14
14
|
* provider (RFC 7591) — is deliberately not here; it's the `ClientRegistrar`
|
|
15
15
|
* seam in charterGrants, wired by the caller that has the provider's URL.
|
|
16
|
+
*
|
|
17
|
+
* `--scopes <file>` supplies a capability→scope registry (a JSON object of
|
|
18
|
+
* string → string) so a role's AAO capabilities (`specify`, `seal`, …) come out
|
|
19
|
+
* as this org's own wire-format scopes (`rewards:redeem`, …) instead of passing
|
|
20
|
+
* through unchanged. This command only reads the file an operator points it
|
|
21
|
+
* at — it does not ship a registry and does not guess one capability's scope
|
|
22
|
+
* from another's.
|
|
16
23
|
*/
|
|
17
24
|
const NINETY_DAYS_SEC = 90 * 24 * 3600;
|
|
18
25
|
export function parseInitArgs(argv) {
|
|
19
26
|
let file = 'flashyos.roles.json';
|
|
20
27
|
let json = false;
|
|
28
|
+
let scopesFile;
|
|
21
29
|
// `flashyid init [file]` — the subcommand token is routing, not a filename.
|
|
22
30
|
const args = argv[0] === 'init' ? argv.slice(1) : argv;
|
|
23
31
|
for (let i = 0; i < args.length; i++) {
|
|
@@ -26,10 +34,12 @@ export function parseInitArgs(argv) {
|
|
|
26
34
|
json = true;
|
|
27
35
|
else if (a === '--file' || a === '-f')
|
|
28
36
|
file = args[++i] ?? file;
|
|
37
|
+
else if (a === '--scopes')
|
|
38
|
+
scopesFile = args[++i] ?? scopesFile;
|
|
29
39
|
else if (a && !a.startsWith('-'))
|
|
30
40
|
file = a;
|
|
31
41
|
}
|
|
32
|
-
return { file, json };
|
|
42
|
+
return scopesFile === undefined ? { file, json } : { file, json, scopesFile };
|
|
33
43
|
}
|
|
34
44
|
/**
|
|
35
45
|
* Run the init mapping and print it. Returns a process exit code: 0 on a clean
|
|
@@ -59,8 +69,38 @@ export function runInit(argv, deps) {
|
|
|
59
69
|
deps.log('✗ a charter needs an accountableTo and a roles[] array');
|
|
60
70
|
return 1;
|
|
61
71
|
}
|
|
72
|
+
let scopeRegistry;
|
|
73
|
+
if (args.scopesFile) {
|
|
74
|
+
let scopesRaw;
|
|
75
|
+
try {
|
|
76
|
+
scopesRaw = deps.readFile(args.scopesFile);
|
|
77
|
+
}
|
|
78
|
+
catch {
|
|
79
|
+
deps.log(`✗ could not read ${args.scopesFile}`);
|
|
80
|
+
return 1;
|
|
81
|
+
}
|
|
82
|
+
let parsed;
|
|
83
|
+
try {
|
|
84
|
+
parsed = JSON.parse(scopesRaw);
|
|
85
|
+
}
|
|
86
|
+
catch {
|
|
87
|
+
deps.log(`✗ ${args.scopesFile} is not valid JSON`);
|
|
88
|
+
return 1;
|
|
89
|
+
}
|
|
90
|
+
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
|
|
91
|
+
deps.log(`✗ ${args.scopesFile} must be a JSON object of capability → scope strings`);
|
|
92
|
+
return 1;
|
|
93
|
+
}
|
|
94
|
+
for (const [cap, scope] of Object.entries(parsed)) {
|
|
95
|
+
if (typeof scope !== 'string') {
|
|
96
|
+
deps.log(`✗ ${args.scopesFile}: "${cap}" must map to a string scope`);
|
|
97
|
+
return 1;
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
scopeRegistry = parsed;
|
|
101
|
+
}
|
|
62
102
|
const exp = deps.nowSec + (deps.expiresInSec ?? NINETY_DAYS_SEC);
|
|
63
|
-
const result = grantsFromCharter(charter, { iat: deps.nowSec, exp, jtiFor: deps.jtiFor });
|
|
103
|
+
const result = grantsFromCharter(charter, { iat: deps.nowSec, exp, jtiFor: deps.jtiFor, scopeRegistry });
|
|
64
104
|
if (args.json) {
|
|
65
105
|
deps.log(JSON.stringify(result.grants, null, 2));
|
|
66
106
|
}
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Rail tokens — flashyID minting the three tokens Flashy Rails verifies.
|
|
3
|
+
*
|
|
4
|
+
* The rail (FlashyLabs/flashy-rails) holds Flashy Gold and settles value. It
|
|
5
|
+
* trusts a token because flashyID SIGNED it: its `FlashyIdVerifier` checks the
|
|
6
|
+
* EdDSA signature against flashyID's published JWKS, checks `iss` and expiry,
|
|
7
|
+
* and then maps the claims onto a Consent / Grant / issuer authorisation. Until
|
|
8
|
+
* now flashyID could sign a general assertion (`signAssertion`) but minted none
|
|
9
|
+
* of the rail's THREE specific shapes — so the rail could only run its dev
|
|
10
|
+
* in-process verifier, never the real `flashyid` one. This module is that
|
|
11
|
+
* missing half, and it is the exact complement of the rail's verifier: anything
|
|
12
|
+
* minted here, `FlashyIdVerifier` accepts (given the matching public key).
|
|
13
|
+
*
|
|
14
|
+
* The claim shapes are the rail's contract, pinned by
|
|
15
|
+
* `flashy-rails/test/flashyid.test.mjs`:
|
|
16
|
+
*
|
|
17
|
+
* issuer — `{ scope: [...,'rewards:issue'] }`. Authorises `earn`; only the
|
|
18
|
+
* estate mints Gold, so this is a privileged service credential.
|
|
19
|
+
* consent — `{ typ:'consent', draftId, holderId, action, approvedAt }`. A
|
|
20
|
+
* holder approving ONE rail draft; the only thing that moves their
|
|
21
|
+
* value out.
|
|
22
|
+
* grant — `{ typ:'grant', grantId, holderId, spenderId, assetId, capMinor,
|
|
23
|
+
* remainingMinor, purpose, expiresAt?, revoked?, parentGrantId? }`.
|
|
24
|
+
* An attenuated, capped delegation the rail draws down.
|
|
25
|
+
*
|
|
26
|
+
* The private key never leaves flashyID; a relying party holds only the public
|
|
27
|
+
* JWKS. `tokens.test.ts` round-trips every shape through jose against a local
|
|
28
|
+
* JWKS and asserts the exact claims the rail reads.
|
|
29
|
+
*/
|
|
30
|
+
import type { KeyLike } from 'jose';
|
|
31
|
+
import type { GrantChain } from '../grants/types.js';
|
|
32
|
+
/** What every rail token needs: flashyID's signing key, its issuer, and the rail as audience. */
|
|
33
|
+
export interface RailSigner {
|
|
34
|
+
/** The EdDSA private key. Issuer-only; never leaves flashyID. */
|
|
35
|
+
privateKey: KeyLike | Uint8Array;
|
|
36
|
+
/** The issuer — must equal the rail's configured expected issuer, e.g. https://id.flashyid.com. */
|
|
37
|
+
issuer: string;
|
|
38
|
+
/** The rail this token is for — lands in `aud`, e.g. the rail's base URL. */
|
|
39
|
+
audience: string;
|
|
40
|
+
/** The signing key id, published in the JWKS so the rail can select it. */
|
|
41
|
+
kid?: string;
|
|
42
|
+
/** Issued-at override, seconds since epoch. For deterministic tests; leave unset in production. */
|
|
43
|
+
iatSec?: number;
|
|
44
|
+
}
|
|
45
|
+
/** Reward-issuance authorisation (the `earn` path). Only the estate mints Gold. */
|
|
46
|
+
export interface IssuerTokenInput {
|
|
47
|
+
/** The service or org authorised to issue, e.g. an estate settlement service id. Lands in `sub`. */
|
|
48
|
+
subject: string;
|
|
49
|
+
/** Scopes; must include the rail's issuer scope. Defaults to exactly that. */
|
|
50
|
+
scope?: string[];
|
|
51
|
+
/** Seconds until the bearer token expires. Short by default — it is a credential, not a session. */
|
|
52
|
+
expiresInSec?: number;
|
|
53
|
+
/** Token id, for replay tracking. */
|
|
54
|
+
jti?: string;
|
|
55
|
+
}
|
|
56
|
+
/** Mint a `rewards:issue`-scoped bearer token for the earn path. */
|
|
57
|
+
export declare function mintIssuerToken(signer: RailSigner, input: IssuerTokenInput): Promise<string>;
|
|
58
|
+
/** A holder's consent to one specific rail draft. */
|
|
59
|
+
export interface ConsentTokenInput {
|
|
60
|
+
/** The rail draft this consent is bound to. */
|
|
61
|
+
draftId: string;
|
|
62
|
+
/** The holder consenting — the id the rail keys Gold on. Also lands in `sub`. */
|
|
63
|
+
holderId: string;
|
|
64
|
+
/** What is being consented to, e.g. 'redeem' | 'transfer'. */
|
|
65
|
+
action: string;
|
|
66
|
+
/** When the holder approved. Defaults to now. */
|
|
67
|
+
approvedAt?: Date;
|
|
68
|
+
/** Seconds until the token expires. Short: a consent is spent immediately. */
|
|
69
|
+
expiresInSec?: number;
|
|
70
|
+
/** Token id, for replay tracking. */
|
|
71
|
+
jti?: string;
|
|
72
|
+
}
|
|
73
|
+
/** Mint a consent token bound to one draft and holder. */
|
|
74
|
+
export declare function mintConsentToken(signer: RailSigner, input: ConsentTokenInput): Promise<string>;
|
|
75
|
+
/** An attenuated, capped delegation the rail draws spend down against. */
|
|
76
|
+
export interface GrantTokenInput {
|
|
77
|
+
/** Unique grant id — the rail's unit of revocation and draw-down. */
|
|
78
|
+
grantId: string;
|
|
79
|
+
/** Whose Gold is spent under this grant. */
|
|
80
|
+
holderId: string;
|
|
81
|
+
/** Who may spend it (an agent surrogate or a service). */
|
|
82
|
+
spenderId: string;
|
|
83
|
+
/** The asset, e.g. Flashy Gold's id. */
|
|
84
|
+
assetId: string;
|
|
85
|
+
/** The ceiling on value moved, in integer minor units. */
|
|
86
|
+
capMinor: number;
|
|
87
|
+
/** How much of the cap remains. Equals capMinor for a fresh grant. */
|
|
88
|
+
remainingMinor?: number;
|
|
89
|
+
/** What the grant is for — the rail records it and it cannot widen on attenuation. */
|
|
90
|
+
purpose: string;
|
|
91
|
+
/** Business expiry of the grant (distinct from the token's own short exp). */
|
|
92
|
+
expiresAt?: Date;
|
|
93
|
+
/** Whether the grant is revoked. */
|
|
94
|
+
revoked?: boolean;
|
|
95
|
+
/** The parent grant this attenuates, if any. */
|
|
96
|
+
parentGrantId?: string | null;
|
|
97
|
+
/** Seconds until the bearer token expires. */
|
|
98
|
+
expiresInSec?: number;
|
|
99
|
+
}
|
|
100
|
+
/** Mint a grant token in the rail's flat grant vocabulary. */
|
|
101
|
+
export declare function mintGrantToken(signer: RailSigner, input: GrantTokenInput): Promise<string>;
|
|
102
|
+
/**
|
|
103
|
+
* Project a flashyID delegation CHAIN onto the rail's flat grant params — the
|
|
104
|
+
* bridge between flashyID's grant vocabulary (a chain of scp/res/lim links) and
|
|
105
|
+
* the rail's (a flat, capped grant).
|
|
106
|
+
*
|
|
107
|
+
* flashyID's chain is the source of truth for delegation: `verifyChain` folds
|
|
108
|
+
* it to an effective grant (tightest limit, earliest expiry, the leaf holder,
|
|
109
|
+
* the accountable root). This maps that onto what the rail draws down:
|
|
110
|
+
*
|
|
111
|
+
* holderId ← the accountable root (whose authority backs the spend)
|
|
112
|
+
* spenderId ← the leaf holder (the agent actually spending)
|
|
113
|
+
* capMinor ← the effective spend_max (the chain's tightest ceiling)
|
|
114
|
+
* expiresAt ← the effective expiry (the earliest across the chain)
|
|
115
|
+
*
|
|
116
|
+
* THE MAPPING IS A DECISION, NOT A DERIVATION, and it is the one thing on this
|
|
117
|
+
* whole path that wants ratification: it treats the chain root as the value
|
|
118
|
+
* holder and the leaf as the spender, which is right when a person/org delegates
|
|
119
|
+
* spend of their own Gold down to an agent. If the estate wants a different
|
|
120
|
+
* correspondence, this function is the single place it lives. Throws if the
|
|
121
|
+
* chain is unsound, if it carries no spend ceiling (an uncapped grant must not
|
|
122
|
+
* become an uncapped rail draw), if `scope` is required and absent, or if the
|
|
123
|
+
* chain's root is not one `extra.trustedRoots` names.
|
|
124
|
+
*
|
|
125
|
+
* `trustedRoots` IS REQUIRED, not optional, and that is deliberate: this is the
|
|
126
|
+
* root-trust-policy decision docs/rail-grant.md named as the one thing left
|
|
127
|
+
* before this path could take a real caller, and the decided answer (estate-
|
|
128
|
+
* named roots only — the `person/`/`org/` ids an AAO charter actually
|
|
129
|
+
* accounts to, via `trustedRootsFromCharters`; see charterGrants.ts) is a
|
|
130
|
+
* closed allow-list, never "any sound chain". A sound chain proves only that it
|
|
131
|
+
* narrows correctly and is held by whoever it says — `verifyChain` — never that
|
|
132
|
+
* its root is one the estate is willing to vouch spend for. Letting a caller
|
|
133
|
+
* omit the check (as this function did until it was wired here) would reopen
|
|
134
|
+
* exactly the fail-open gap `enforce()`'s 0.2.0 fix closed on the other primitive
|
|
135
|
+
* in this package: a boundary with no way to pass a trust set is a boundary a
|
|
136
|
+
* caller can walk around by never building one. There is deliberately no
|
|
137
|
+
* "trust everyone" sentinel; a caller that genuinely wants that passes its own
|
|
138
|
+
* unbounded set, in its own code, rather than getting it by omission.
|
|
139
|
+
*/
|
|
140
|
+
export declare function railGrantFromChain(signer: RailSigner, chain: GrantChain, extra: {
|
|
141
|
+
grantId: string;
|
|
142
|
+
assetId: string;
|
|
143
|
+
purpose: string;
|
|
144
|
+
trustedRoots: Iterable<string>;
|
|
145
|
+
nowSec?: number;
|
|
146
|
+
requireScope?: string;
|
|
147
|
+
expiresInSec?: number;
|
|
148
|
+
}): Promise<string>;
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
import { signAssertion } from '../sdk/sign.js';
|
|
2
|
+
import { verifyChain, rootsWithin } from '../grants/grants.js';
|
|
3
|
+
/** Mint a `rewards:issue`-scoped bearer token for the earn path. */
|
|
4
|
+
export function mintIssuerToken(signer, input) {
|
|
5
|
+
return signAssertion({
|
|
6
|
+
privateKey: signer.privateKey,
|
|
7
|
+
issuer: signer.issuer,
|
|
8
|
+
audience: signer.audience,
|
|
9
|
+
subject: input.subject,
|
|
10
|
+
kid: signer.kid,
|
|
11
|
+
iatSec: signer.iatSec,
|
|
12
|
+
expiresInSec: input.expiresInSec ?? 300,
|
|
13
|
+
jti: input.jti,
|
|
14
|
+
extraClaims: { scope: input.scope ?? ['rewards:issue'] },
|
|
15
|
+
});
|
|
16
|
+
}
|
|
17
|
+
/** Mint a consent token bound to one draft and holder. */
|
|
18
|
+
export function mintConsentToken(signer, input) {
|
|
19
|
+
return signAssertion({
|
|
20
|
+
privateKey: signer.privateKey,
|
|
21
|
+
issuer: signer.issuer,
|
|
22
|
+
audience: signer.audience,
|
|
23
|
+
subject: input.holderId,
|
|
24
|
+
kid: signer.kid,
|
|
25
|
+
iatSec: signer.iatSec,
|
|
26
|
+
expiresInSec: input.expiresInSec ?? 120,
|
|
27
|
+
jti: input.jti,
|
|
28
|
+
extraClaims: {
|
|
29
|
+
typ: 'consent',
|
|
30
|
+
draftId: input.draftId,
|
|
31
|
+
holderId: input.holderId,
|
|
32
|
+
action: input.action,
|
|
33
|
+
approvedAt: (input.approvedAt ?? new Date()).toISOString(),
|
|
34
|
+
},
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
/** Mint a grant token in the rail's flat grant vocabulary. */
|
|
38
|
+
export function mintGrantToken(signer, input) {
|
|
39
|
+
return signAssertion({
|
|
40
|
+
privateKey: signer.privateKey,
|
|
41
|
+
issuer: signer.issuer,
|
|
42
|
+
audience: signer.audience,
|
|
43
|
+
subject: input.holderId,
|
|
44
|
+
kid: signer.kid,
|
|
45
|
+
iatSec: signer.iatSec,
|
|
46
|
+
expiresInSec: input.expiresInSec ?? 300,
|
|
47
|
+
jti: input.grantId,
|
|
48
|
+
extraClaims: {
|
|
49
|
+
typ: 'grant',
|
|
50
|
+
grantId: input.grantId,
|
|
51
|
+
holderId: input.holderId,
|
|
52
|
+
spenderId: input.spenderId,
|
|
53
|
+
assetId: input.assetId,
|
|
54
|
+
capMinor: input.capMinor,
|
|
55
|
+
remainingMinor: input.remainingMinor ?? input.capMinor,
|
|
56
|
+
purpose: input.purpose,
|
|
57
|
+
...(input.expiresAt ? { expiresAt: input.expiresAt.toISOString() } : {}),
|
|
58
|
+
revoked: input.revoked ?? false,
|
|
59
|
+
parentGrantId: input.parentGrantId ?? null,
|
|
60
|
+
},
|
|
61
|
+
});
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Project a flashyID delegation CHAIN onto the rail's flat grant params — the
|
|
65
|
+
* bridge between flashyID's grant vocabulary (a chain of scp/res/lim links) and
|
|
66
|
+
* the rail's (a flat, capped grant).
|
|
67
|
+
*
|
|
68
|
+
* flashyID's chain is the source of truth for delegation: `verifyChain` folds
|
|
69
|
+
* it to an effective grant (tightest limit, earliest expiry, the leaf holder,
|
|
70
|
+
* the accountable root). This maps that onto what the rail draws down:
|
|
71
|
+
*
|
|
72
|
+
* holderId ← the accountable root (whose authority backs the spend)
|
|
73
|
+
* spenderId ← the leaf holder (the agent actually spending)
|
|
74
|
+
* capMinor ← the effective spend_max (the chain's tightest ceiling)
|
|
75
|
+
* expiresAt ← the effective expiry (the earliest across the chain)
|
|
76
|
+
*
|
|
77
|
+
* THE MAPPING IS A DECISION, NOT A DERIVATION, and it is the one thing on this
|
|
78
|
+
* whole path that wants ratification: it treats the chain root as the value
|
|
79
|
+
* holder and the leaf as the spender, which is right when a person/org delegates
|
|
80
|
+
* spend of their own Gold down to an agent. If the estate wants a different
|
|
81
|
+
* correspondence, this function is the single place it lives. Throws if the
|
|
82
|
+
* chain is unsound, if it carries no spend ceiling (an uncapped grant must not
|
|
83
|
+
* become an uncapped rail draw), if `scope` is required and absent, or if the
|
|
84
|
+
* chain's root is not one `extra.trustedRoots` names.
|
|
85
|
+
*
|
|
86
|
+
* `trustedRoots` IS REQUIRED, not optional, and that is deliberate: this is the
|
|
87
|
+
* root-trust-policy decision docs/rail-grant.md named as the one thing left
|
|
88
|
+
* before this path could take a real caller, and the decided answer (estate-
|
|
89
|
+
* named roots only — the `person/`/`org/` ids an AAO charter actually
|
|
90
|
+
* accounts to, via `trustedRootsFromCharters`; see charterGrants.ts) is a
|
|
91
|
+
* closed allow-list, never "any sound chain". A sound chain proves only that it
|
|
92
|
+
* narrows correctly and is held by whoever it says — `verifyChain` — never that
|
|
93
|
+
* its root is one the estate is willing to vouch spend for. Letting a caller
|
|
94
|
+
* omit the check (as this function did until it was wired here) would reopen
|
|
95
|
+
* exactly the fail-open gap `enforce()`'s 0.2.0 fix closed on the other primitive
|
|
96
|
+
* in this package: a boundary with no way to pass a trust set is a boundary a
|
|
97
|
+
* caller can walk around by never building one. There is deliberately no
|
|
98
|
+
* "trust everyone" sentinel; a caller that genuinely wants that passes its own
|
|
99
|
+
* unbounded set, in its own code, rather than getting it by omission.
|
|
100
|
+
*/
|
|
101
|
+
export async function railGrantFromChain(signer, chain, extra) {
|
|
102
|
+
const nowSec = extra.nowSec ?? Math.floor(Date.now() / 1000);
|
|
103
|
+
const effective = verifyChain(chain, nowSec, new Set());
|
|
104
|
+
if (!effective.ok) {
|
|
105
|
+
throw new Error(`railGrantFromChain: unsound delegation chain (${effective.code})`);
|
|
106
|
+
}
|
|
107
|
+
const rooted = rootsWithin(effective, extra.trustedRoots);
|
|
108
|
+
if (rooted !== true) {
|
|
109
|
+
throw new Error(`railGrantFromChain: ${rooted.code}${rooted.detail ? ` (${rooted.detail})` : ''}`);
|
|
110
|
+
}
|
|
111
|
+
if (extra.requireScope && !effective.scp.includes(extra.requireScope)) {
|
|
112
|
+
throw new Error(`railGrantFromChain: chain does not grant the required scope "${extra.requireScope}"`);
|
|
113
|
+
}
|
|
114
|
+
if (typeof effective.lim.spend_max !== 'number') {
|
|
115
|
+
throw new Error('railGrantFromChain: chain has no spend ceiling; an uncapped grant must not become an uncapped rail draw');
|
|
116
|
+
}
|
|
117
|
+
const capMinor = effective.lim.spend_max;
|
|
118
|
+
return mintGrantToken(signer, {
|
|
119
|
+
grantId: extra.grantId,
|
|
120
|
+
holderId: effective.root,
|
|
121
|
+
spenderId: effective.holder,
|
|
122
|
+
assetId: extra.assetId,
|
|
123
|
+
capMinor,
|
|
124
|
+
remainingMinor: capMinor,
|
|
125
|
+
purpose: extra.purpose,
|
|
126
|
+
expiresAt: new Date(effective.exp * 1000),
|
|
127
|
+
parentGrantId: chain.length > 1 ? chain[chain.length - 2].jti : null,
|
|
128
|
+
expiresInSec: extra.expiresInSec,
|
|
129
|
+
});
|
|
130
|
+
}
|
package/dist/sdk/index.d.ts
CHANGED
|
@@ -12,5 +12,7 @@ export { verifyAssertion, authorize } from './verify.js';
|
|
|
12
12
|
export type { FlashyIdAssertion, VerifyOptions } from './verify.js';
|
|
13
13
|
export { signAssertion } from './sign.js';
|
|
14
14
|
export type { SignAssertionInput } from './sign.js';
|
|
15
|
-
export {
|
|
16
|
-
export type {
|
|
15
|
+
export { signRevocationList, verifyRevocationList } from './revocation.js';
|
|
16
|
+
export type { SignRevocationListInput, VerifyRevocationListOptions, VerifiedRevocationList } from './revocation.js';
|
|
17
|
+
export { issueRoot, attenuate, verifyChain, permits, rootsWithin, grantFromCharterRole, impactRank, IMPACT_ORDER, emptyRevocationList, revoke, revokedAsOf, revocationOf, extendsList, validateRevocationList, verifyChainAgainst, isAccountableSigner, REVOCATION_LIST_VERSION, REVOCATION_REASON_MIN, REVOCATION_SIGNER_PREFIXES, } from '../grants/index.js';
|
|
18
|
+
export type { GrantChain, GrantLink, Limit, Impact, RefusalCode, Refusal, EffectiveGrant, GrantResult, Demand, IssueRootInput, AttenuateInput, RevocationEntry, RevocationList, RevocationRefusal, RevocationRefusalCode, RevokeInput, ChainVerdict, } from '../grants/index.js';
|
package/dist/sdk/index.js
CHANGED
|
@@ -10,4 +10,5 @@
|
|
|
10
10
|
*/
|
|
11
11
|
export { verifyAssertion, authorize } from './verify.js';
|
|
12
12
|
export { signAssertion } from './sign.js';
|
|
13
|
-
export {
|
|
13
|
+
export { signRevocationList, verifyRevocationList } from './revocation.js';
|
|
14
|
+
export { issueRoot, attenuate, verifyChain, permits, rootsWithin, grantFromCharterRole, impactRank, IMPACT_ORDER, emptyRevocationList, revoke, revokedAsOf, revocationOf, extendsList, validateRevocationList, verifyChainAgainst, isAccountableSigner, REVOCATION_LIST_VERSION, REVOCATION_REASON_MIN, REVOCATION_SIGNER_PREFIXES, } from '../grants/index.js';
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
import { type KeyLike, type JWTVerifyGetKey } from 'jose';
|
|
2
|
+
import { type RevocationList } from '../grants/revocation.js';
|
|
3
|
+
/**
|
|
4
|
+
* The revocation list on the wire — a `revocation/1` document a stranger can
|
|
5
|
+
* fetch and verify with nothing but the issuer's public JWKS.
|
|
6
|
+
*
|
|
7
|
+
* It is signed the way an assertion is signed and nothing else: an EdDSA JWS
|
|
8
|
+
* (`SignJWT`, `alg: 'EdDSA'`, the issuer's `kid`) whose payload is the list
|
|
9
|
+
* under `iss`, so the public half is already at `/.well-known/jwks.json` and a
|
|
10
|
+
* relying party that can verify an assertion can verify the list with the same
|
|
11
|
+
* key set. No second key scheme, no list-specific secret.
|
|
12
|
+
*
|
|
13
|
+
* Deterministic: `iatSec` is required, never defaulted from a clock, so the
|
|
14
|
+
* same list at the same revision signs to the same bytes for the same key, and
|
|
15
|
+
* `verifyRevocationList` reads no clock either — a list does not expire (a
|
|
16
|
+
* reader decides its own freshness by the revision and `iat` it carries).
|
|
17
|
+
*/
|
|
18
|
+
export interface SignRevocationListInput {
|
|
19
|
+
/** The issuer's EdDSA private key. Issuer-only; never leaves it. */
|
|
20
|
+
privateKey: KeyLike | Uint8Array;
|
|
21
|
+
/** The signing key id, published in the JWKS so a verifier can select it. */
|
|
22
|
+
kid?: string;
|
|
23
|
+
/** When this revision was signed, seconds since epoch. Injected, never read from a clock. */
|
|
24
|
+
iatSec: number;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Sign a revocation list as a compact JWS. Throws on a list that does not
|
|
28
|
+
* validate — an issuer must never put its key on a malformed record.
|
|
29
|
+
*/
|
|
30
|
+
export declare function signRevocationList(list: RevocationList, input: SignRevocationListInput): Promise<string>;
|
|
31
|
+
export interface VerifyRevocationListOptions {
|
|
32
|
+
/** The issuer the list must be signed by — must match the JWS `iss` and the list's `issuer`. */
|
|
33
|
+
issuer: string;
|
|
34
|
+
/** Injectable for tests; defaults to the issuer's /.well-known/jwks.json via `createRemoteJWKSet`. */
|
|
35
|
+
getKey?: JWTVerifyGetKey | KeyLike | Uint8Array;
|
|
36
|
+
}
|
|
37
|
+
/** The verified list and when its issuer signed that revision. */
|
|
38
|
+
export interface VerifiedRevocationList {
|
|
39
|
+
list: RevocationList;
|
|
40
|
+
/** The `iat` the issuer put on this revision, seconds since epoch. */
|
|
41
|
+
signedAt: number;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Verify a signed revocation list: signature against the issuer's JWKS, `iss`,
|
|
45
|
+
* then every structural rule of `revocation/1` (contiguous revisions,
|
|
46
|
+
* accountable signers, reasons of length, time never running backwards).
|
|
47
|
+
* Returns `null` on any failure — a list that does not verify is no list, and
|
|
48
|
+
* a relying party holding none should go on using the revision it last
|
|
49
|
+
* verified rather than an empty set (unread is not zero).
|
|
50
|
+
*/
|
|
51
|
+
export declare function verifyRevocationList(jws: string | undefined | null, opts: VerifyRevocationListOptions): Promise<VerifiedRevocationList | null>;
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { SignJWT, jwtVerify } from 'jose';
|
|
2
|
+
import { validateRevocationList, REVOCATION_LIST_VERSION } from '../grants/revocation.js';
|
|
3
|
+
/**
|
|
4
|
+
* Sign a revocation list as a compact JWS. Throws on a list that does not
|
|
5
|
+
* validate — an issuer must never put its key on a malformed record.
|
|
6
|
+
*/
|
|
7
|
+
export async function signRevocationList(list, input) {
|
|
8
|
+
const checked = validateRevocationList(list);
|
|
9
|
+
if ('ok' in checked)
|
|
10
|
+
throw new Error(`signRevocationList: refusing to sign a malformed list (${checked.code}: ${checked.detail ?? ''})`);
|
|
11
|
+
if (!Number.isInteger(input.iatSec))
|
|
12
|
+
throw new Error('signRevocationList: iatSec must be an integer number of seconds');
|
|
13
|
+
return new SignJWT({ typ: REVOCATION_LIST_VERSION, v: checked.v, head: checked.head, entries: checked.entries })
|
|
14
|
+
.setProtectedHeader({ alg: 'EdDSA', ...(input.kid ? { kid: input.kid } : {}) })
|
|
15
|
+
.setIssuer(checked.issuer)
|
|
16
|
+
.setIssuedAt(input.iatSec)
|
|
17
|
+
.sign(input.privateKey);
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Verify a signed revocation list: signature against the issuer's JWKS, `iss`,
|
|
21
|
+
* then every structural rule of `revocation/1` (contiguous revisions,
|
|
22
|
+
* accountable signers, reasons of length, time never running backwards).
|
|
23
|
+
* Returns `null` on any failure — a list that does not verify is no list, and
|
|
24
|
+
* a relying party holding none should go on using the revision it last
|
|
25
|
+
* verified rather than an empty set (unread is not zero).
|
|
26
|
+
*/
|
|
27
|
+
export async function verifyRevocationList(jws, opts) {
|
|
28
|
+
if (!jws)
|
|
29
|
+
return null;
|
|
30
|
+
const key = opts.getKey ?? (await remoteKey(opts.issuer));
|
|
31
|
+
try {
|
|
32
|
+
const { payload } = await jwtVerify(jws, key, { issuer: opts.issuer, algorithms: ['EdDSA'] });
|
|
33
|
+
if (payload.typ !== REVOCATION_LIST_VERSION || typeof payload.iat !== 'number')
|
|
34
|
+
return null;
|
|
35
|
+
const list = validateRevocationList({ v: payload.v, issuer: payload.iss, head: payload.head, entries: payload.entries });
|
|
36
|
+
if ('ok' in list)
|
|
37
|
+
return null;
|
|
38
|
+
return { list, signedAt: payload.iat };
|
|
39
|
+
}
|
|
40
|
+
catch {
|
|
41
|
+
return null;
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
async function remoteKey(issuer) {
|
|
45
|
+
const { createRemoteJWKSet } = await import('jose');
|
|
46
|
+
return createRemoteJWKSet(new URL(`${issuer.replace(/\/+$/, '')}/.well-known/jwks.json`));
|
|
47
|
+
}
|
package/dist/sdk/verify.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { type JWTVerifyGetKey, type KeyLike } from 'jose';
|
|
2
2
|
import { type Demand } from '../grants/grants.js';
|
|
3
|
+
import { type RevocationList } from '../grants/revocation.js';
|
|
3
4
|
import { type GrantChain, type GrantResult } from '../grants/types.js';
|
|
4
5
|
/**
|
|
5
6
|
* @flashyid/sdk — the relying-party verify surface.
|
|
@@ -70,6 +71,14 @@ export declare function verifyAssertion(token: string | undefined | null, opts:
|
|
|
70
71
|
export declare function authorize(token: string | undefined | null, demand: Demand, opts: VerifyOptions & {
|
|
71
72
|
nowSec: number;
|
|
72
73
|
revokedJtis?: ReadonlySet<string>;
|
|
74
|
+
/**
|
|
75
|
+
* The issuer's `revocation/1` list, as `verifyRevocationList` returned it.
|
|
76
|
+
* Unioned with `revokedJtis`; the answer carries `revocationsAsOf`, the
|
|
77
|
+
* revision the verdict was computed against.
|
|
78
|
+
*/
|
|
79
|
+
revocations?: RevocationList;
|
|
80
|
+
/** The revision of `revocations` to evaluate at; defaults to its head. */
|
|
81
|
+
asOf?: number;
|
|
73
82
|
/**
|
|
74
83
|
* The roots this relying party accepts authority from — the `iss` of each
|
|
75
84
|
* chain's root link, typically the `accountableTo` of every AAO charter it
|
|
@@ -82,4 +91,5 @@ export declare function authorize(token: string | undefined | null, demand: Dema
|
|
|
82
91
|
}): Promise<{
|
|
83
92
|
assertion: FlashyIdAssertion;
|
|
84
93
|
result: GrantResult;
|
|
94
|
+
revocationsAsOf?: number;
|
|
85
95
|
} | null>;
|
package/dist/sdk/verify.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { jwtVerify, createRemoteJWKSet } from 'jose';
|
|
2
2
|
import { verifyChain, permits, rootsWithin } from '../grants/grants.js';
|
|
3
|
+
import { verifyChainAgainst } from '../grants/revocation.js';
|
|
3
4
|
import { IMPACT_ORDER } from '../grants/types.js';
|
|
4
5
|
function isStringArray(v) {
|
|
5
6
|
return Array.isArray(v) && v.every((x) => typeof x === 'string');
|
|
@@ -26,7 +27,9 @@ function isGrantLink(v) {
|
|
|
26
27
|
isLimit(l.lim) &&
|
|
27
28
|
typeof l.iat === 'number' &&
|
|
28
29
|
typeof l.exp === 'number' &&
|
|
29
|
-
typeof l.
|
|
30
|
+
(l.nbf === undefined || typeof l.nbf === 'number') &&
|
|
31
|
+
typeof l.jti === 'string' &&
|
|
32
|
+
(typeof l.par === 'string' || l.par === null));
|
|
30
33
|
}
|
|
31
34
|
/**
|
|
32
35
|
* A `del` claim is attacker-adjacent wire data: it arrives inside a signed
|
|
@@ -108,12 +111,22 @@ export async function authorize(token, demand, opts) {
|
|
|
108
111
|
}
|
|
109
112
|
return { assertion, result: { ok: false, code: 'empty_chain', detail: 'assertion carries no delegation' } };
|
|
110
113
|
}
|
|
111
|
-
|
|
114
|
+
let verified;
|
|
115
|
+
const stamp = {};
|
|
116
|
+
if (opts.revocations) {
|
|
117
|
+
const verdict = verifyChainAgainst(assertion.del, opts.nowSec, opts.revocations, { asOf: opts.asOf, extraRevoked: opts.revokedJtis });
|
|
118
|
+
verified = verdict.result;
|
|
119
|
+
stamp.revocationsAsOf = verdict.asOf;
|
|
120
|
+
}
|
|
121
|
+
else {
|
|
122
|
+
verified = verifyChain(assertion.del, opts.nowSec, opts.revokedJtis ?? new Set());
|
|
123
|
+
}
|
|
112
124
|
if (!verified.ok)
|
|
113
|
-
return { assertion, result: verified };
|
|
125
|
+
return { assertion, result: verified, ...stamp };
|
|
114
126
|
if (verified.holder !== assertion.sub) {
|
|
115
127
|
return {
|
|
116
128
|
assertion,
|
|
129
|
+
...stamp,
|
|
117
130
|
result: {
|
|
118
131
|
ok: false,
|
|
119
132
|
code: 'broken_chain',
|
|
@@ -127,8 +140,8 @@ export async function authorize(token, demand, opts) {
|
|
|
127
140
|
if (opts.trustedRoots !== undefined) {
|
|
128
141
|
const rooted = rootsWithin(verified, opts.trustedRoots);
|
|
129
142
|
if (rooted !== true)
|
|
130
|
-
return { assertion, result: rooted };
|
|
143
|
+
return { assertion, result: rooted, ...stamp };
|
|
131
144
|
}
|
|
132
145
|
const p = permits(verified, demand);
|
|
133
|
-
return { assertion, result: p === true ? verified : p };
|
|
146
|
+
return { assertion, result: p === true ? verified : p, ...stamp };
|
|
134
147
|
}
|
package/docs/enforcement-gate.md
CHANGED
|
@@ -16,7 +16,7 @@ ask: expose `authorize()` as a synchronous gate on `decide()`.
|
|
|
16
16
|
|---|---|
|
|
17
17
|
| `ALLOW` | the grant permits the action, below the human-approval bar — proceed |
|
|
18
18
|
| `ESCALATE` | permitted, but the action's impact is **at or above** the chain's `approval_at_or_above` — a named human must co-sign |
|
|
19
|
-
| `DENY` | the chain is unsound (`expired`, `revoked`, `chain_widened`, `broken_chain`) or the action is `out_of_mandate` (scope / resource / spend exceeded) |
|
|
19
|
+
| `DENY` | the chain is unsound (`expired`, `not_yet_valid`, `revoked`, `chain_widened`, `broken_chain`) or the action is `out_of_mandate` (scope / resource / spend exceeded) |
|
|
20
20
|
|
|
21
21
|
`DENY` carries the kernel's `RefusalCode`, so the "why" is auditable. `ESCALATE`
|
|
22
22
|
carries the impact bar that triggered it.
|
|
@@ -31,26 +31,43 @@ const result = evaluateGrant(chain, { scope: 'seal', impact: 'CRITICAL' }, { now
|
|
|
31
31
|
// → { action: 'ESCALATE', escalateAtOrAbove: 'CRITICAL' }
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
- `evaluateGrant(chain, demand, { nowSec, revokedJtis })` —
|
|
34
|
+
- `evaluateGrant(chain, demand, { nowSec, revokedJtis, revocations, asOf })` —
|
|
35
|
+
the pure core. It decides against the LEAF's effective authority (the
|
|
36
|
+
intersection down the chain), never the root's. `revocations` is the
|
|
37
|
+
issuer's `revocation/1` list (unioned with `revokedJtis`), `asOf` the
|
|
38
|
+
revision to decide at (default: its head), and the result then carries
|
|
39
|
+
`revocationsAsOf` so the verdict can be restated against that revision.
|
|
40
|
+
A `revoked` DENY's `reason` names the link, who withdrew it, and why.
|
|
35
41
|
- `EnforcementAdapter` — `evaluate(decision) => Promise<EnforcementResult>`; the
|
|
36
42
|
seam an enterprise registers to gate decisions.
|
|
37
43
|
- `grantAdapter()` — an adapter backed by `evaluateGrant` (the real gate).
|
|
38
|
-
- `recordOnly` — the default adapter
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
+
- `recordOnly` — the default adapter for an org with **no adapter registered**:
|
|
45
|
+
always `ALLOW`. (A *registered* adapter that becomes unreachable is a
|
|
46
|
+
different case — see `enforce` below, which fails closed since 0.2.0.)
|
|
47
|
+
- `enforce(decision, adapter, { timeoutMs = 5000, onUnavailable, unavailable })`
|
|
48
|
+
— the operational contract: await the adapter within a timeout; on error,
|
|
49
|
+
timeout, or a non-verdict response, raise `onUnavailable` (the CRITICAL alert
|
|
50
|
+
an operator wires to monitoring) and answer per `unavailable` —
|
|
51
|
+
**`'deny'` (the default, since 0.2.0) fails closed**; `'escalate'` hands the
|
|
52
|
+
decision to a human; `'allow'` records and proceeds, same as before 0.2.0.
|
|
44
53
|
|
|
45
54
|
## Design posture
|
|
46
55
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
56
|
+
Gating is opt-in: an org with **no adapter registered** stays on `recordOnly`,
|
|
57
|
+
which always `ALLOW`s — the mesh must never halt an agent that asked for no
|
|
58
|
+
enforcement in the first place. But an org that *did* register an adapter asked
|
|
59
|
+
for a real boundary, and a boundary that answers `ALLOW` the moment its policy
|
|
60
|
+
service goes down is one an attacker clears by unplugging it (external audit,
|
|
61
|
+
2026-10-10, see `CHANGELOG.md` 0.2.0). So **since 0.2.0**, `enforce()` fails
|
|
62
|
+
**closed** by default when a configured adapter is unreachable: `DENY` with code
|
|
63
|
+
`adapter_unavailable`, not `ALLOW`. The pre-0.2.0 "never block" behaviour is
|
|
64
|
+
still available — pass `unavailable: 'allow'` — but it is now a choice written
|
|
65
|
+
in the caller's own code rather than the gate's silent default. A natural
|
|
66
|
+
commercial tier ("Governance Pro") sits on top of a real, fail-closed gate.
|
|
53
67
|
|
|
54
68
|
Tests: `src/enforce/gate.test.ts` — ALLOW / ESCALATE / DENY across scope, spend,
|
|
55
|
-
expiry, and revocation; record-only default;
|
|
56
|
-
with the alert firing
|
|
69
|
+
expiry, not-before, and revocation (by set and by list); record-only default;
|
|
70
|
+
adapter throw + timeout fallback with the alert firing; and, over random
|
|
71
|
+
chains, that a child never ALLOWs what its parent DENIES and the gate answers
|
|
72
|
+
for the leaf rather than the root. The revocation list itself is
|
|
73
|
+
`src/grants/revocation.ts` (`README.md`, *Runtime gating and revocation*).
|