@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.
@@ -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
+ }
@@ -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 { issueRoot, attenuate, verifyChain, permits, rootsWithin, grantFromCharterRole, impactRank, IMPACT_ORDER, } from '../grants/index.js';
16
- export type { GrantChain, GrantLink, Limit, Impact, RefusalCode, Refusal, EffectiveGrant, GrantResult, Demand, IssueRootInput, AttenuateInput, } from '../grants/index.js';
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 { issueRoot, attenuate, verifyChain, permits, rootsWithin, grantFromCharterRole, impactRank, IMPACT_ORDER, } from '../grants/index.js';
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
+ }
@@ -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>;
@@ -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.jti === 'string');
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
- const verified = verifyChain(assertion.del, opts.nowSec, opts.revokedJtis ?? new Set());
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
  }
@@ -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 })` — the pure core.
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: always `ALLOW`. An org with no adapter, or
39
- an unreachable one, must never have its agents halted.
40
- - `enforce(decision, adapter, { timeoutMs = 5000, onUnavailable })` — the
41
- operational contract: await the adapter within a timeout; on error or timeout,
42
- fall back to `ALLOW` (recorded only) and raise `onUnavailable` — the CRITICAL
43
- alert an operator wires to monitoring.
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
- The gate **preserves "never block"** as the default. Gating is opt-in: only an
48
- org that registers an adapter is gated, and even then an unreachable adapter
49
- falls back to record-only rather than halting the agent's critical path. This is
50
- the honest-governance posture the brief called sound — extended, not replaced,
51
- with a real gate for those who want one. A natural commercial tier
52
- ("Governance Pro") sits exactly here.
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; adapter throw + timeout fallback
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*).