@feasibleone/blong-gogo 1.34.0 → 1.35.0

package/src/exit.intent.test.ts

@@ -9,9 +9,16 @@ import load from './loadServer.ts';
  * intent names (which is what `runServer` used to do with
  * `process.env.CI && !intents.includes('playwright')`).
  *
- * Only `load` is exercised, never `start`, so nothing binds a port and no
- * watcher is created — the assertions here are about the flag, and the
- * "no listener" property is checked by actually running `blong cli`.
+ * Only `load` is exercised, never `start`, so no watcher is created and the
+ * assertions here are about the flag — the "no listener" property is checked by
+ * actually running `blong cli`.
+ *
+ * Every load is stopped though, because `load` is not as idle as it looks: the
+ * `dev` and `integration` intents open the semantic-log cluster service, which
+ * listens on a socket, and a registry that is never stopped leaves it open. The
+ * suite then passes every assertion and reports `timeout!` — what a live server
+ * does to a tap process that has nothing left to run (`Registry.stop` closes it
+ * for the same reason).
  */
 
 /**
@@ -41,7 +48,11 @@ async function exitFor(intents: string[]): Promise<boolean | undefined> {
         {},
         intents,
     );
-    return registry.exit;
+    try {
+        return registry.exit;
+    } finally {
+        await registry.stop();
+    }
 }
 
 test('cli and db are short-lived', async t => {
@@ -93,6 +104,10 @@ test('the cli intent turns off everything that would outlive a command', async t
         {},
         ['cli'],
     );
-    t.equal(registry.exit, true, 'short-lived');
-    t.ok(Array.isArray(registry.describe?.().realms), 'the realm still loaded');
+    try {
+        t.equal(registry.exit, true, 'short-lived');
+        t.ok(Array.isArray(registry.describe?.().realms), 'the realm still loaded');
+    } finally {
+        await registry.stop();
+    }
 });

package/src/frameworkRealms.test.ts

@@ -0,0 +1,177 @@
+import {mkdtempSync, mkdirSync, rmSync, writeFileSync} from 'node:fs';
+import Module, {createRequire} from 'node:module';
+import {tmpdir} from 'node:os';
+import {dirname, join} from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {server} from '@feasibleone/blong';
+import {test} from 'tap';
+
+import load from './loadServer.ts';
+
+/**
+ * Which realms the framework loads beside a suite is decided by the suite's
+ * *manifest*, not by what happens to resolve.
+ *
+ * The two questions look like one, and only differ when the ambient resolution
+ * lies: `createRequire(...).resolve()` falls back to `NODE_PATH`, and the tap
+ * runner points that at the pnpm store — where every workspace package can be
+ * found, including a published copy of blong-server. Under `blong-dev test` the
+ * framework therefore loaded realms into suites that declare none of them, and
+ * `demo/blong-cli` (a command that runs on the `cli` intent and reads no
+ * database) died with `Unknown database 'blong-cli'` (F-206).
+ *
+ * The fixture below reproduces exactly that shape without touching the runner:
+ * a package the ambient resolution can find, a suite beside a manifest that does
+ * or does not declare it, and one assertion per case. The realm that loads is a
+ * marker realm of its own rather than the real blong-server, which would want a
+ * database and a database name of its own.
+ */
+
+/**
+ * The marker realm the fake blong-server package exports.
+ *
+ * A realm is a factory carrying the framework's `kind` symbol, and the symbol is
+ * registered with `Symbol.for`, so a fixture can be a realm without reaching for
+ * `@feasibleone/blong` — which is what lets it live in a tmp directory. It is CJS
+ * because the runner transpiles the suite to CJS, so the loader's `import()` of
+ * it is a `require()`, and requiring an ES module from there is a cycle.
+ */
+const MARKER_REALM = `const Kind = Symbol.for('blong:kind');
+
+module.exports = Object.defineProperty(
+    () => ({
+        url: require('node:url').pathToFileURL(__filename).href,
+        pkg: {name: 'blong-server', version: '0.0.0'},
+        config: {default: {}},
+    }),
+    Kind,
+    {value: 'solution'},
+);
+`;
+
+/**
+ * A directory that is both the suite's home and a `NODE_PATH` entry.
+ *
+ * `node_modules/@feasibleone/blong-server` is the package the ambient resolution
+ * answers with, and its `exports` maps the pinned `/server.ts` subpath onto the
+ * marker realm above. `suite.ts` is named by the suite's `url` but never
+ * imported: it only gives `createRequire(suiteUrl)('./package.json')` a directory
+ * to resolve the suite's manifest in.
+ */
+function fixture(declaresMarker: boolean): {url: string; dispose: () => void} {
+    const dir = mkdtempSync(join(tmpdir(), 'blong-framework-realms-'));
+    const marker = join(dir, 'node_modules', '@feasibleone', 'blong-server');
+    mkdirSync(marker, {recursive: true});
+    writeFileSync(
+        join(marker, 'package.json'),
+        JSON.stringify({name: 'blong-server', exports: {'./server.ts': './server.cjs'}}),
+    );
+    writeFileSync(join(marker, 'server.cjs'), MARKER_REALM);
+    writeFileSync(join(dir, 'suite.ts'), '');
+    writeFileSync(
+        join(dir, 'package.json'),
+        JSON.stringify({
+            name: 'framework-realms-fixture',
+            version: '0.0.0',
+            ...(declaresMarker ? {dependencies: {'@feasibleone/blong-server': '1.0.0'}} : {}),
+        }),
+    );
+    return {
+        url: pathToFileURL(join(dir, 'suite.ts')).href,
+        dispose: () => rmSync(dir, {recursive: true, force: true}),
+    };
+}
+
+/**
+ * Run `body` with `dir` on the module paths Node resolves against, which is the
+ * effect `NODE_PATH` has in a child process. `globalPaths` is read on every
+ * resolve, so pushing onto it is enough — no re-init and no environment
+ * manipulation, and the entry is taken back off afterwards.
+ */
+async function withAmbientResolution<T>(dir: string, body: () => Promise<T>): Promise<T> {
+    const {globalPaths} = Module as unknown as {globalPaths: string[]};
+    const path = join(dir, 'node_modules');
+    globalPaths.unshift(path);
+    try {
+        return await body();
+    } finally {
+        globalPaths.splice(globalPaths.indexOf(path), 1);
+    }
+}
+
+/**
+ * A suite that names no children: everything it loads, it loads because its
+ * manifest declares it — or because the ambient resolution found it, which is
+ * the bug this asserts against.
+ */
+const suite = (url: string, pkg?: {name: string; version: string}) =>
+    server(
+        () =>
+            ({
+                url,
+                ...(pkg ? {pkg} : {}),
+                children: [],
+                config: {default: {}},
+            }) as never,
+    );
+
+test('a realm the suite does not declare is not loaded, though NODE_PATH resolves it', async t => {
+    const {url, dispose} = fixture(false);
+    try {
+        await withAmbientResolution(dirname(fileURLToPath(url)), async () => {
+            // The premise: the marker realm *is* resolvable from the suite's own
+            // location, so the loader would have loaded it had it asked by
+            // resolution.
+            t.match(
+                createRequire(url).resolve('@feasibleone/blong-server/server.ts'),
+                /blong-server/,
+                'the ambient resolution finds the realm the suite does not declare',
+            );
+            const registry = await load(suite(url) as never, 'undeclared', {}, ['cli']);
+            t.notOk(
+                registry.describe?.().realms.includes('server'),
+                'and the loader leaves it out',
+            );
+        });
+    } finally {
+        dispose();
+    }
+});
+
+test('a realm the suite declares is loaded', async t => {
+    const {url, dispose} = fixture(true);
+    try {
+        await withAmbientResolution(dirname(fileURLToPath(url)), async () => {
+            const registry = await load(suite(url) as never, 'declared', {}, ['cli']);
+            t.ok(
+                registry.describe?.().realms.includes('server'),
+                'the declared realm is loaded',
+            );
+        });
+    } finally {
+        dispose();
+    }
+});
+
+test('a trimmed manifest does not un-declare a realm', async t => {
+    // `blong-suite/server.ts` passes `{name, version}` and nothing else, so the
+    // dependencies only exist in the file beside it. Reading the trimmed manifest as
+    // the whole answer would drop the realm that suite depends on.
+    const {url, dispose} = fixture(true);
+    try {
+        await withAmbientResolution(dirname(fileURLToPath(url)), async () => {
+            const registry = await load(
+                suite(url, {name: 'framework-realms-fixture', version: '0.0.0'}) as never,
+                'trimmed',
+                {},
+                ['cli'],
+            );
+            t.ok(
+                registry.describe?.().realms.includes('server'),
+                'the file beside the suite still counts',
+            );
+        });
+    } finally {
+        dispose();
+    }
+});

package/src/grant.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Grants: a short-lived token that asks for one capability, on one request.
+ *
+ * What matters here is that the mechanism is *narrow*: it verifies only what it
+ * signed, honours only what it knows, and answers "no grant" — never an error —
+ * for everything else, because it arrives on a header anybody can set.
+ */
+import {exportJWK, generateKeyPair, importJWK, SignJWT} from 'jose';
+import t from 'tap';
+import {devSignKey} from './devKeys.ts';
+import {
+    DEFAULT_TTL_SECONDS,
+    granted,
+    grantedCalls,
+    grantKeyFrom,
+    mintGrant,
+    parseTtl,
+    verifyGrant,
+} from './grant.ts';
+
+const secondsAgo = (seconds: number): number => Math.floor(Date.now() / 1000) - seconds;
+
+t.test('a minted grant verifies, and carries only the capability it was asked for', async t => {
+    const token = await mintGrant({cap: ['calls'], ttlSeconds: 60});
+    const claims = await verifyGrant(token);
+    t.equal(granted(claims, 'calls'), true, 'the capability is honoured');
+    t.equal(claims?.cap.length, 1, 'and nothing else is claimed');
+    t.ok((claims?.exp ?? 0) > secondsAgo(0), 'the expiry is in the future');
+    t.end();
+});
+
+t.test('the default lifetime is minutes, not a session', async t => {
+    t.equal(DEFAULT_TTL_SECONDS, 900);
+    const claims = await verifyGrant(await mintGrant({cap: ['calls']}));
+    const lifetime = (claims?.exp ?? 0) - (claims?.iat ?? 0);
+    t.equal(
+        lifetime,
+        DEFAULT_TTL_SECONDS,
+        'the token expires a quarter of an hour after it was minted',
+    );
+    t.end();
+});
+
+t.test('an expired grant is no grant', async t => {
+    // Signed with a key this process does not hold, so the failure is the expiry
+    // and not the signature: the token below is well-formed in every other way.
+    const {privateKey} = await generateKeyPair('ES384', {extractable: true});
+    const jwk = {...(await exportJWK(privateKey)), alg: 'ES384'};
+    const expired = await new SignJWT({cap: ['calls']})
+        .setProtectedHeader({alg: 'ES384'})
+        .setIssuedAt(secondsAgo(120))
+        .setExpirationTime(secondsAgo(60))
+        .sign(await importJWK(jwk, 'ES384'));
+    t.equal(
+        await verifyGrant(expired, jwk),
+        undefined,
+        'a token that has expired verifies as nothing',
+    );
+    t.end();
+});
+
+t.test('a token signed by another key is refused', async t => {
+    const {privateKey} = await generateKeyPair('ES384', {extractable: true});
+    const other = {...(await exportJWK(privateKey)), alg: 'ES384'};
+    const foreign = await mintGrant({cap: ['calls'], ttlSeconds: 60, key: other});
+    t.equal(await verifyGrant(foreign), undefined, 'the framework key does not verify it');
+    t.equal((await verifyGrant(foreign, other))?.cap.join(), 'calls', 'and its own key does');
+    t.end();
+});
+
+t.test('a tampered or absent token is no grant, not an error', async t => {
+    const token = await mintGrant({cap: ['calls'], ttlSeconds: 60});
+    t.equal(await verifyGrant(`${token.slice(0, -3)}abc`), undefined, 'a mangled signature');
+    t.equal(await verifyGrant('not-a-token'), undefined, 'nonsense');
+    t.equal(await verifyGrant(''), undefined, 'an empty header');
+    t.equal(await verifyGrant(undefined), undefined, 'and no header at all');
+    t.end();
+});
+
+t.test('a capability this build does not know is dropped, not trusted', async t => {
+    const claims = await verifyGrant(await mintGrant({cap: [], ttlSeconds: 60}));
+    t.same(claims?.cap, [], 'an empty claim grants nothing');
+    t.equal(granted(claims, 'calls'), false);
+    t.equal(granted(undefined, 'calls'), false, 'and neither does a missing one');
+    t.end();
+});
+
+t.test('minting without a private key says so', async t => {
+    const {publicKey} = await generateKeyPair('ES384', {extractable: true});
+    const publicOnly = {...(await exportJWK(publicKey)), alg: 'ES384'};
+    await t.rejects(
+        mintGrant({cap: ['calls'], key: publicOnly}),
+        /no private half/,
+        'a public key cannot sign, and the failure names why',
+    );
+    t.end();
+});
+
+t.test('a generated key verifies nothing rather than the development key', async t => {
+    // A gateway that generated its own keys must not fall back to the committed
+    // development key: that would accept a token anybody can mint with the
+    // repository in hand.
+    t.equal(
+        await verifyGrant(await mintGrant({cap: ['calls']}), {generate: {alg: 'ES384'}}),
+        undefined,
+        'a key that exists only in the process that made it verifies no grant',
+    );
+    t.end();
+});
+
+t.test('the gateway verifies with the key it signs MLE with, unless one is named', t => {
+    t.same(
+        grantKeyFrom({sign: {env: 'GATEWAY_SIGN_KEY'}}),
+        {env: 'GATEWAY_SIGN_KEY'},
+        'the sign key by default',
+    );
+    t.same(
+        grantKeyFrom({sign: {env: 'GATEWAY_SIGN_KEY'}, grant: {key: devSignKey}}),
+        devSignKey,
+        'gateway.grant.key wins when a deployment names one',
+    );
+    t.equal(grantKeyFrom({}), undefined, 'and no key at all means no verification');
+    t.end();
+});
+
+t.test('a ttl reads the way a person writes one', t => {
+    t.equal(parseTtl(undefined), DEFAULT_TTL_SECONDS, 'absent is the default');
+    t.equal(parseTtl('45'), 45, 'a bare number is seconds');
+    t.equal(parseTtl('45s'), 45);
+    t.equal(parseTtl('15m'), 900);
+    t.equal(parseTtl('2h'), 7200);
+    t.throws(
+        () => parseTtl('15 minutes'),
+        /Unrecognized --ttl/,
+        'anything else is refused, not guessed',
+    );
+    t.throws(() => parseTtl('0'), /at least a second/);
+    t.end();
+});
+
+t.test('an env key that is not a JWK is reported rather than used', async t => {
+    process.env['BLONG_TEST_GRANT_KEY'] = 'not json';
+    t.teardown(() => delete process.env['BLONG_TEST_GRANT_KEY']);
+    await t.rejects(mintGrant({cap: ['calls'], key: {env: 'BLONG_TEST_GRANT_KEY'}}), /valid JSON/);
+    t.equal(
+        await verifyGrant('anything', {env: 'BLONG_TEST_GRANT_KEY'}),
+        undefined,
+        'verification refuses it too',
+    );
+    t.end();
+});
+
+t.test('a grant asks for calls through the one seam the gateway uses', async t => {
+    const token = await mintGrant({cap: ['calls'], ttlSeconds: 60});
+    t.equal(await grantedCalls(token, undefined), true, 'a granted request asks for calls');
+    t.equal(
+        await grantedCalls(undefined, undefined),
+        false,
+        'a request with no grant asks for nothing',
+    );
+    t.equal(
+        await grantedCalls('not-a-token', undefined),
+        false,
+        'and a tampered one asks for nothing',
+    );
+    const expired = await verifyGrant(await mintGrant({cap: ['calls'], ttlSeconds: 1}), undefined);
+    t.ok((expired?.exp ?? 0) > 0, 'a short-lived token still verifies while it is live');
+});

package/src/grant.ts

@@ -0,0 +1,273 @@
+/**
+ * Short-lived grants: one signed token that asks for one capability, on one
+ * request, for a few minutes.
+ *
+ * Troubleshooting a *running* system needs data that is far too expensive — or
+ * too revealing — to produce for every request: the calls of a flow, the payloads
+ * of a message, the debug records of a component. The alternative to always
+ * collecting them is a switch that can be turned on for the next request, which
+ * is what this is:
+ *
+ *     blong grant calls --ttl 15m
+ *     curl -H 'x-blong-grant: <token>' ...
+ *
+ * - **Short-lived**: `exp` is enforced at verification, so a leaked token is
+ *   worth a quarter of an hour, not a session.
+ * - **One capability per token** (or a few, in `cap`), so granting one thing
+ *   never implies another.
+ * - **Signed with the gateway's own key** — the one it can verify with and a
+ *   client cannot mint with. A deployment sets `GATEWAY_SIGN_KEY`; a checkout
+ *   uses the committed development key, which is what makes the command work
+ *   locally with no setup.
+ *
+ * The token is *not* forwarded: the gateway verifies it at its earliest hook and
+ * republishes the answer as a plain capability marker in `$meta.forward`
+ * (`callTrace.ts`), so a downstream process reads a decided capability instead of
+ * a credential, and needs no key of its own. Capability #2 is added by naming it
+ * in {@link Capability} and asking for it where its work happens — the transport,
+ * the verification and the propagation are already shared.
+ *
+ * ## Failure is "no grant"
+ *
+ * An absent, malformed, expired or wrongly-signed token returns `undefined`
+ * rather than throwing. These tokens arrive on a header anybody can set, so a
+ * bad one is a request with no capabilities — never a rejected request. A
+ * telemetry switch must not be able to fail the call it was meant to illuminate.
+ */
+
+import {importJWK, jwtVerify, SignJWT, type JWK} from 'jose';
+import {CALLS_CAPABILITY} from './callTrace.ts';
+import {devSignKey} from './devKeys.ts';
+
+/** The capabilities a grant may ask for. One name per capability, never a wildcard. */
+export type Capability = 'calls';
+
+/** Every capability this build knows, so an unknown claim is dropped rather than trusted. */
+const KNOWN: readonly Capability[] = ['calls'];
+
+/** How a key is named to the framework. */
+export type GrantKey = {env: string} | {generate: unknown} | JWK;
+
+/** Fifteen minutes: long enough to reproduce a failure, short enough to forget. */
+export const DEFAULT_TTL_SECONDS = 900;
+
+/** The claims a grant carries. Nothing else is read back out of the token. */
+export interface GrantClaims {
+    cap: Capability[];
+    /** Expiry, in seconds since the epoch, as JWT spells it. */
+    exp?: number;
+    iat?: number;
+}
+
+function isCapability(value: unknown): value is Capability {
+    return typeof value === 'string' && (KNOWN as readonly string[]).includes(value);
+}
+
+/**
+ * Resolve a key spec to a JWK.
+ *
+ * `{env}` exists so a deployment can keep the key material in its secret
+ * configuration rather than in the merged config a `/api/sys/config` dump would
+ * print; the literal `devSignKey` is what a checkout falls back to.
+ */
+function resolveKey(key: GrantKey | undefined): JWK | undefined {
+    if (key === undefined) {
+        return devSignKey as JWK;
+    }
+    if ('generate' in key) {
+        // A generated key exists only in the process that made it: a gateway whose
+        // keys were generated (no `GATEWAY_SIGN_KEY`, no configured key) verifies no
+        // grant at all, and in particular does not fall back to the committed
+        // development key and start accepting tokens anybody could mint.
+        return undefined;
+    }
+    if ('env' in key) {
+        const value = process.env[key.env];
+        if (!value) return undefined;
+        try {
+            return JSON.parse(value) as JWK;
+        } catch {
+            throw new Error(`Grant key "${key.env}" is set but does not contain valid JSON`);
+        }
+    }
+    return key;
+}
+
+/** The signing algorithm the JWK names, defaulting to the framework's own. */
+function algorithmOf(jwk: JWK): string {
+    return typeof jwk.alg === 'string' ? jwk.alg : 'ES384';
+}
+
+/** The public half of a JWK, which is all verification needs. */
+function publicOf(jwk: JWK): JWK {
+    const {d: _d, p: _p, q: _q, dp: _dp, dq: _dq, qi: _qi, ...rest} = jwk;
+    return rest as JWK;
+}
+
+/**
+ * Mint a grant for `cap`, good for `ttlSeconds`.
+ *
+ * Throws when the key has no private half: minting a token nobody can verify is
+ * a worse answer than saying so, and reaching here without one means the
+ * deployment's key is configured as public-only.
+ */
+export async function mintGrant({
+    cap,
+    ttlSeconds = DEFAULT_TTL_SECONDS,
+    key,
+}: {
+    cap: Capability[];
+    ttlSeconds?: number;
+    key?: GrantKey;
+}): Promise<string> {
+    const jwk = resolveKey(key);
+    if (!jwk) {
+        throw new Error('No grant key is configured (set GATEWAY_SIGN_KEY or pass --key)');
+    }
+    if (jwk.d === undefined) {
+        throw new Error('The grant key has no private half, so no grant can be minted with it');
+    }
+    const alg = algorithmOf(jwk);
+    const signer = await importJWK(jwk, alg);
+    return new SignJWT({cap})
+        .setProtectedHeader({alg, ...(jwk.kid === undefined ? {} : {kid: jwk.kid})})
+        .setIssuedAt()
+        .setExpirationTime(`${ttlSeconds}s`)
+        .sign(signer);
+}
+
+/**
+ * Verify a grant and read its capabilities.
+ *
+ * `undefined` for anything that does not verify — absent, malformed, expired,
+ * signed by another key, or naming a capability this build does not know. The
+ * caller treats that as "no capabilities", never as an error.
+ */
+export async function verifyGrant(
+    token: string | undefined,
+    key?: GrantKey,
+): Promise<GrantClaims | undefined> {
+    if (typeof token !== 'string' || token.length === 0) return undefined;
+    let jwk: JWK | undefined;
+    try {
+        jwk = resolveKey(key);
+    } catch {
+        return undefined;
+    }
+    if (!jwk || jwk.d === undefined) return undefined;
+    try {
+        const {payload} = await jwtVerify(token, await importJWK(publicOf(jwk), algorithmOf(jwk)));
+        const cap = Array.isArray(payload.cap) ? payload.cap.filter(isCapability) : [];
+        return {
+            cap,
+            exp: typeof payload.exp === 'number' ? payload.exp : undefined,
+            iat: typeof payload.iat === 'number' ? payload.iat : undefined,
+        };
+    } catch {
+        return undefined;
+    }
+}
+
+/** True when `grant` asked for `capability`. */
+export function granted(grant: GrantClaims | undefined, capability: Capability): boolean {
+    return grant?.cap.includes(capability) === true;
+}
+
+/**
+ * Where the gateway's verification key comes from.
+ *
+ * `gateway.grant.key` when a deployment names one, else the gateway's sign key
+ * spec — the key the gateway already resolves for MLE, whose private half stays
+ * on the server. Reading it here rather than in `Gateway.ts` keeps the two
+ * callers (a running gateway and the CLI that mints for it) on one rule.
+ */
+export function grantKeyFrom(config: unknown): GrantKey | undefined {
+    const grant = (config as {grant?: {key?: GrantKey}} | undefined)?.grant;
+    if (grant?.key !== undefined) return grant.key;
+    const sign = (config as {sign?: GrantKey} | undefined)?.sign;
+    return sign === undefined ? undefined : sign;
+}
+
+/**
+ * Whether a grant asks for a flow's calls.
+ *
+ * The whole of what the gateway's earliest hook asks a grant: verify it once, and
+ * turn the answer into the capability the flow is served under. Named rather than
+ * inlined there so the seam can be tested without an HTTP server — the token's
+ * checks and the capability's name are what could drift, and neither needs a
+ * request to prove.
+ */
+export async function grantedCalls(
+    token: string | undefined,
+    key: GrantKey | undefined,
+): Promise<boolean> {
+    return granted(await verifyGrant(token, key), CALLS_CAPABILITY);
+}
+
+/**
+ * Read a duration the way a person writes one: `45`, `45s`, `15m`, `2h`.
+ *
+ * A bare number is seconds, which is the unit the token itself uses. Anything
+ * else is refused rather than guessed at — a TTL that silently means minutes
+ * where the operator meant hours is a grant that outlives the investigation it
+ * was minted for.
+ */
+export function parseTtl(value: unknown): number {
+    if (value === undefined) return DEFAULT_TTL_SECONDS;
+    const text = String(value).trim();
+    const match = /^(\d+)(s|m|h)?$/.exec(text);
+    if (!match) {
+        throw new Error(`Unrecognized --ttl "${text}": expected seconds, or a number with s/m/h`);
+    }
+    const amount = Number(match[1]);
+    const unit = match[2] ?? 's';
+    const seconds = unit === 'h' ? amount * 3600 : unit === 'm' ? amount * 60 : amount;
+    if (seconds < 1)
+        throw new Error(`Unrecognized --ttl "${text}": a grant must last at least a second`);
+    return seconds;
+}
+
+/**
+ * `blong grant <capability> [--ttl=15m] [--key=<jwk|ENV_VAR>]`.
+ *
+ * Prints the token on stdout — and nothing else, so it can be used in a shell
+ * substitution — and exits non-zero with a reason on stderr when it cannot be
+ * minted. It does not load a suite: minting is one signature over the key the
+ * deployment already has, and a command that had to boot an application to
+ * produce a token would be unusable exactly when it is wanted (a running
+ * deployment whose behaviour is in question).
+ */
+export async function runGrantCommand(
+    positionals: string[],
+    flags: {ttl?: unknown; key?: unknown} | Record<string, unknown>,
+): Promise<void> {
+    const {ttl, key: keyFlag} = flags as {ttl?: unknown; key?: unknown};
+    const requested = positionals.slice(1).filter(name => name.length > 0);
+    const unknown = requested.filter(name => !isCapability(name));
+    if (requested.length === 0 || unknown.length > 0) {
+        throw new Error(
+            `Usage: blong grant <capability> [--ttl=15m]\n` +
+                `Known capabilities: ${KNOWN.join(', ')}`,
+        );
+    }
+    const key = typeof keyFlag === 'string' ? parseKeyFlag(keyFlag) : undefined;
+    const token = await mintGrant({
+        cap: requested as Capability[],
+        ttlSeconds: parseTtl(ttl),
+        ...(key === undefined ? {} : {key}),
+    });
+    process.stdout.write(`${token}\n`);
+}
+
+/**
+ * Read `--key`: either an env var name holding the JWK, or the JWK itself.
+ *
+ * The name is the form a deployment uses (`--key=GATEWAY_SIGN_KEY`, beside the
+ * variable the gateway reads), and the literal is the form an operator uses when
+ * the key is not in the environment they are minting from.
+ */
+function parseKeyFlag(value: string): GrantKey {
+    const text = value.trim();
+    if (text.startsWith('{')) return JSON.parse(text) as JWK;
+    return {env: text};
+}