@graphorin/cli 0.5.0

package/dist/commands/token.d.ts

@@ -0,0 +1,109 @@
+import { CommonOutputOptions } from "../internal/output.js";
+import { TokenMetadata } from "@graphorin/security";
+
+//#region src/commands/token.d.ts
+
+/** @stable */
+interface TokenCommonOptions extends CommonOutputOptions {
+  readonly config?: string;
+}
+/** @stable */
+interface TokenCreateOptions extends TokenCommonOptions {
+  readonly label?: string;
+  /** Comma-separated scope list. */
+  readonly scopes: ReadonlyArray<string>;
+  /** Duration string: `30d`, `12h`, `90m`, `45s`. */
+  readonly expiresIn?: string;
+  readonly env?: 'live' | 'test';
+}
+/** @stable */
+interface TokenCreateResult {
+  readonly id: string;
+  readonly label?: string;
+  readonly scopes: ReadonlyArray<string>;
+  readonly raw: string;
+  readonly expiresAt?: string;
+}
+/**
+ * Create a token. Returns the raw value once + the persisted record.
+ *
+ * @stable
+ */
+declare function runTokenCreate(options: TokenCreateOptions): Promise<TokenCreateResult>;
+/** @stable */
+interface TokenListOptions extends TokenCommonOptions {
+  readonly includeRevoked?: boolean;
+}
+/**
+ * List token metadata.
+ *
+ * @stable
+ */
+declare function runTokenList(options?: TokenListOptions): Promise<ReadonlyArray<TokenMetadata>>;
+/** @stable */
+interface TokenRevokeOptions extends TokenCommonOptions {
+  readonly id: string;
+}
+/**
+ * Revoke a single token.
+ *
+ * @stable
+ */
+declare function runTokenRevoke(options: TokenRevokeOptions): Promise<TokenMetadata | undefined>;
+/** @stable */
+interface TokenRotateOptions extends TokenCommonOptions {
+  readonly id: string;
+  readonly env?: 'live' | 'test';
+}
+/**
+ * Revoke an existing token and immediately mint a fresh one with the
+ * same scopes. Returns the new raw token bytes once.
+ *
+ * @stable
+ */
+declare function runTokenRotate(options: TokenRotateOptions): Promise<TokenCreateResult>;
+/** @stable */
+interface TokenRekeyOptions extends TokenCommonOptions {
+  readonly env?: 'live' | 'test';
+}
+/**
+ * Re-issue every active token. Used after a known compromise.
+ *
+ * @stable
+ */
+declare function runTokenRekey(options?: TokenRekeyOptions): Promise<ReadonlyArray<{
+  readonly oldId: string;
+  readonly newId: string;
+  readonly raw: string;
+}>>;
+/** @stable */
+interface TokenVerifyOptions extends CommonOutputOptions {
+  readonly token: string;
+  /** Optional override of the expected token prefix. */
+  readonly prefix?: string;
+}
+/** @stable */
+interface TokenVerifyResult {
+  readonly ok: boolean;
+  readonly reason?: string;
+}
+/**
+ * Offline checksum verification. Confirms the structural shape, the
+ * environment marker, and the CRC checksum but does NOT consult the
+ * token store — it only proves the token was minted by a Graphorin
+ * helper.
+ *
+ * @stable
+ */
+declare function runTokenVerify(options: TokenVerifyOptions): TokenVerifyResult;
+/**
+ * Tiny duration parser. Accepts `Ns`, `Nm`, `Nh`, `Nd`. Returns
+ * milliseconds. Throws on invalid input — surfaced as a fail-fast at
+ * the CLI boundary.
+ *
+ * @internal
+ */
+declare function parseDuration(input: string): number;
+//#endregion
+export { TokenCommonOptions, TokenCreateOptions, TokenCreateResult, TokenListOptions, TokenRekeyOptions, TokenRevokeOptions, TokenRotateOptions, TokenVerifyOptions, TokenVerifyResult, parseDuration, runTokenCreate, runTokenList, runTokenRekey, runTokenRevoke, runTokenRotate, runTokenVerify };
+//# sourceMappingURL=token.d.ts.map

package/dist/commands/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","names":[],"sources":["../../src/commands/token.ts"],"sourcesContent":[],"mappings":";;;;;AAgMA;AAWsB,UA5JL,kBAAA,SAA2B,mBA4JR,CAAA;EAAU,SAAA,MAAA,CAAA,EAAA,MAAA;;;AAA4B,UAvJzD,kBAAA,SAA2B,kBAuJ8B,CAAA;EAuCzD,SAAA,KAAA,CAAA,EAAA,MAAkB;EASb;EACX,SAAA,MAAA,EArMQ,aAqMR,CAAA,MAAA,CAAA;EAET;EADC,SAAA,SAAA,CAAA,EAAA,MAAA;EAAO,SAAA,GAAA,CAAA,EAAA,MAAA,GAAA,MAAA;AAqCV;AAOA;AAagB,UAxPC,iBAAA,CAwPuB;EA2BxB,SAAA,EAAA,EAAA,MAAa;;mBAhRV;;;;;;;;;iBAUG,cAAA,UAAwB,qBAAqB,QAAQ;;UA8C1D,gBAAA,SAAyB;;;;;;;;iBASpB,YAAA,WACX,mBACR,QAAQ,cAAc;;UA2BR,kBAAA,SAA2B;;;;;;;;iBAStB,cAAA,UACX,qBACR,QAAQ;;UAsBM,kBAAA,SAA2B;;;;;;;;;;iBAWtB,cAAA,UAAwB,qBAAqB,QAAQ;;UAuC1D,iBAAA,SAA0B;;;;;;;;iBASrB,aAAA,WACX,oBACR,QACD;;;;;;UAoCe,kBAAA,SAA2B;;;;;;UAO3B,iBAAA;;;;;;;;;;;;iBAaD,cAAA,UAAwB,qBAAqB;;;;;;;;iBA2B7C,aAAA"}

package/dist/commands/token.js

@@ -0,0 +1,246 @@
+import { brand, defaultPrintSink, emitReport, statusMarker } from "../internal/output.js";
+import { EXIT_CODES } from "../internal/exit.js";
+import { openStoreContext } from "../internal/store-context.js";
+import { createToken, listTokens, rekeyTokens, revokeToken, rotateToken, verifyOffline } from "@graphorin/security";
+
+//#region src/commands/token.ts
+/**
+* `graphorin token` — manage server auth tokens.
+*
+* The subcommand thin-wraps the library functions in
+* `@graphorin/security/auth` (`createToken`, `listTokens`,
+* `revokeToken`, `rotateToken`, `rekeyTokens`, `verifyOffline`). Per
+* Phase 15 § Tokens the surface ships:
+*
+*  - `graphorin token create --label <name> --scopes <list> [--expires-in <duration>]`
+*  - `graphorin token list`
+*  - `graphorin token revoke <id>`
+*  - `graphorin token rotate <id>`
+*  - `graphorin token rekey`
+*  - `graphorin token verify <token>`
+*
+* The raw token bytes are shown to the operator at most once — at the
+* call site of `create` / `rotate` / `rekey`. They are wrapped in a
+* {@link SecretValue} on the way back to keep accidental logging out
+* of the codepath; the CLI prints them via `value.use((s) => ...)` so
+* the bytes never live as a plain string variable longer than needed.
+*
+* @packageDocumentation
+*/
+const ONE_DAY_MS = 1440 * 60 * 1e3;
+/**
+* Create a token. Returns the raw value once + the persisted record.
+*
+* @stable
+*/
+async function runTokenCreate(options) {
+	const ctx = await openStoreContext({
+		...options.config !== void 0 ? { config: options.config } : {},
+		requirePepper: true
+	});
+	try {
+		if (ctx.pepper === void 0) throw new Error("[graphorin/cli] internal: pepper resolution should have populated ctx.pepper");
+		const env = options.env ?? "live";
+		const expiresInMs = options.expiresIn !== void 0 ? parseDuration(options.expiresIn) : void 0;
+		const created = await createToken({
+			tokenStore: ctx.store.authTokens,
+			pepper: ctx.pepper,
+			env,
+			scopes: options.scopes,
+			...options.label !== void 0 ? { label: options.label } : {},
+			...expiresInMs !== void 0 ? { expiresInMs } : {}
+		});
+		const raw = await created.raw.use((s) => String(s));
+		const out = Object.freeze({
+			id: created.record.id,
+			...created.record.label !== void 0 ? { label: created.record.label } : {},
+			scopes: Object.freeze([...created.record.scopes]),
+			raw,
+			...created.record.expiresAt !== void 0 ? { expiresAt: created.record.expiresAt } : {}
+		});
+		emitReport(options, out, () => {
+			const print = options.print ?? defaultPrintSink;
+			print(brand(`token created (id=${out.id}, scopes=${out.scopes.join(",")})`));
+			print(brand(`raw token (shown ONCE):`));
+			print(`  ${out.raw}`);
+			if (out.expiresAt !== void 0) print(brand(`expires at: ${out.expiresAt}`));
+		});
+		return out;
+	} finally {
+		await ctx.close();
+	}
+}
+/**
+* List token metadata.
+*
+* @stable
+*/
+async function runTokenList(options = {}) {
+	const ctx = await openStoreContext({ ...options.config !== void 0 ? { config: options.config } : {} });
+	try {
+		const list = await listTokens(ctx.store.authTokens, { includeRevoked: options.includeRevoked === true });
+		emitReport(options, list, () => {
+			const print = options.print ?? defaultPrintSink;
+			if (list.length === 0) {
+				print(brand("no tokens registered."));
+				return;
+			}
+			print(brand(`${list.length} token(s):`));
+			for (const t of list) print(`  ${t.revokedAt !== void 0 ? statusMarker("warn") : statusMarker("ok")} ${t.id} (label=${t.label ?? "-"}, scopes=${t.scopes.join(",")})`);
+		});
+		return list;
+	} finally {
+		await ctx.close();
+	}
+}
+/**
+* Revoke a single token.
+*
+* @stable
+*/
+async function runTokenRevoke(options) {
+	const ctx = await openStoreContext({ ...options.config !== void 0 ? { config: options.config } : {} });
+	try {
+		const result = await revokeToken(ctx.store.authTokens, options.id);
+		emitReport(options, result ?? null, () => {
+			const print = options.print ?? defaultPrintSink;
+			if (result === void 0) {
+				print(brand(`token '${options.id}' not found.`));
+				process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;
+				return;
+			}
+			print(brand(`token '${result.id}' revoked at ${result.revokedAt ?? "<now>"}`));
+		});
+		return result;
+	} finally {
+		await ctx.close();
+	}
+}
+/**
+* Revoke an existing token and immediately mint a fresh one with the
+* same scopes. Returns the new raw token bytes once.
+*
+* @stable
+*/
+async function runTokenRotate(options) {
+	const ctx = await openStoreContext({
+		...options.config !== void 0 ? { config: options.config } : {},
+		requirePepper: true
+	});
+	try {
+		if (ctx.pepper === void 0) throw new Error("[graphorin/cli] internal: pepper missing.");
+		const env = options.env ?? "live";
+		const result = await rotateToken({
+			tokenStore: ctx.store.authTokens,
+			pepper: ctx.pepper,
+			id: options.id,
+			env
+		});
+		const raw = await result.next.raw.use((s) => String(s));
+		const out = Object.freeze({
+			id: result.next.record.id,
+			...result.next.record.label !== void 0 ? { label: result.next.record.label } : {},
+			scopes: Object.freeze([...result.next.record.scopes]),
+			raw,
+			...result.next.record.expiresAt !== void 0 ? { expiresAt: result.next.record.expiresAt } : {}
+		});
+		emitReport(options, out, () => {
+			const print = options.print ?? defaultPrintSink;
+			print(brand(`token '${result.old.id}' revoked + replaced by '${out.id}'`));
+			print(brand("raw token (shown ONCE):"));
+			print(`  ${raw}`);
+		});
+		return out;
+	} finally {
+		await ctx.close();
+	}
+}
+/**
+* Re-issue every active token. Used after a known compromise.
+*
+* @stable
+*/
+async function runTokenRekey(options = {}) {
+	const ctx = await openStoreContext({
+		...options.config !== void 0 ? { config: options.config } : {},
+		requirePepper: true
+	});
+	try {
+		if (ctx.pepper === void 0) throw new Error("[graphorin/cli] internal: pepper missing.");
+		const result = await rekeyTokens({
+			tokenStore: ctx.store.authTokens,
+			pepper: ctx.pepper,
+			env: options.env ?? "live"
+		});
+		const out = [];
+		for (const [oldId, created] of result) {
+			const raw = await created.raw.use((s) => String(s));
+			out.push(Object.freeze({
+				oldId,
+				newId: created.record.id,
+				raw
+			}));
+		}
+		const frozen = Object.freeze(out);
+		emitReport(options, frozen, () => {
+			const print = options.print ?? defaultPrintSink;
+			print(brand(`rekeyed ${frozen.length} token(s):`));
+			for (const row of frozen) {
+				print(`  - old=${row.oldId} new=${row.newId}`);
+				print(`    raw: ${row.raw}`);
+			}
+		});
+		return frozen;
+	} finally {
+		await ctx.close();
+	}
+}
+/**
+* Offline checksum verification. Confirms the structural shape, the
+* environment marker, and the CRC checksum but does NOT consult the
+* token store — it only proves the token was minted by a Graphorin
+* helper.
+*
+* @stable
+*/
+function runTokenVerify(options) {
+	const result = verifyOffline(options.token, { ...options.prefix !== void 0 ? { acceptPrefix: options.prefix } : {} });
+	const out = Object.freeze({
+		ok: result.ok,
+		...result.ok ? {} : { reason: result.reason }
+	});
+	emitReport(options, out, () => {
+		const print = options.print ?? defaultPrintSink;
+		if (out.ok) {
+			print(brand(`token format ${statusMarker("ok")} (offline checksum verified)`));
+			return;
+		}
+		print(brand(`token format ${statusMarker("fail")} (${out.reason ?? "unknown reason"})`));
+		process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;
+	});
+	return out;
+}
+/**
+* Tiny duration parser. Accepts `Ns`, `Nm`, `Nh`, `Nd`. Returns
+* milliseconds. Throws on invalid input — surfaced as a fail-fast at
+* the CLI boundary.
+*
+* @internal
+*/
+function parseDuration(input) {
+	const match = /^(\d+)\s*([smhd])$/i.exec(input.trim());
+	if (!match) throw new Error(`[graphorin/cli] invalid --expires-in '${input}'. Use the form '<number><s|m|h|d>' (e.g. 30d).`);
+	const value = Number.parseInt(match[1], 10);
+	const unit = match[2].toLowerCase();
+	switch (unit) {
+		case "s": return value * 1e3;
+		case "m": return value * 6e4;
+		case "h": return value * 60 * 6e4;
+		case "d": return value * ONE_DAY_MS;
+		default: throw new Error(`[graphorin/cli] invalid --expires-in unit '${unit}'.`);
+	}
+}
+
+//#endregion
+export { parseDuration, runTokenCreate, runTokenList, runTokenRekey, runTokenRevoke, runTokenRotate, runTokenVerify };
+//# sourceMappingURL=token.js.map

package/dist/commands/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","names":["out: TokenCreateResult","out: Array<{ readonly oldId: string; readonly newId: string; readonly raw: string }>","out: TokenVerifyResult"],"sources":["../../src/commands/token.ts"],"sourcesContent":["/**\n * `graphorin token` — manage server auth tokens.\n *\n * The subcommand thin-wraps the library functions in\n * `@graphorin/security/auth` (`createToken`, `listTokens`,\n * `revokeToken`, `rotateToken`, `rekeyTokens`, `verifyOffline`). Per\n * Phase 15 § Tokens the surface ships:\n *\n *  - `graphorin token create --label <name> --scopes <list> [--expires-in <duration>]`\n *  - `graphorin token list`\n *  - `graphorin token revoke <id>`\n *  - `graphorin token rotate <id>`\n *  - `graphorin token rekey`\n *  - `graphorin token verify <token>`\n *\n * The raw token bytes are shown to the operator at most once — at the\n * call site of `create` / `rotate` / `rekey`. They are wrapped in a\n * {@link SecretValue} on the way back to keep accidental logging out\n * of the codepath; the CLI prints them via `value.use((s) => ...)` so\n * the bytes never live as a plain string variable longer than needed.\n *\n * @packageDocumentation\n */\n\nimport {\n  createToken,\n  listTokens,\n  rekeyTokens,\n  revokeToken,\n  rotateToken,\n  type TokenMetadata,\n  verifyOffline,\n} from '@graphorin/security';\n\nimport { EXIT_CODES } from '../internal/exit.js';\nimport {\n  brand,\n  type CommonOutputOptions,\n  defaultPrintSink,\n  emitReport,\n  statusMarker,\n} from '../internal/output.js';\nimport { openStoreContext } from '../internal/store-context.js';\n\nconst ONE_DAY_MS = 24 * 60 * 60 * 1000;\n\n/** @stable */\nexport interface TokenCommonOptions extends CommonOutputOptions {\n  readonly config?: string;\n}\n\n/** @stable */\nexport interface TokenCreateOptions extends TokenCommonOptions {\n  readonly label?: string;\n  /** Comma-separated scope list. */\n  readonly scopes: ReadonlyArray<string>;\n  /** Duration string: `30d`, `12h`, `90m`, `45s`. */\n  readonly expiresIn?: string;\n  readonly env?: 'live' | 'test';\n}\n\n/** @stable */\nexport interface TokenCreateResult {\n  readonly id: string;\n  readonly label?: string;\n  readonly scopes: ReadonlyArray<string>;\n  readonly raw: string;\n  readonly expiresAt?: string;\n}\n\n/**\n * Create a token. Returns the raw value once + the persisted record.\n *\n * @stable\n */\nexport async function runTokenCreate(options: TokenCreateOptions): Promise<TokenCreateResult> {\n  const ctx = await openStoreContext({\n    ...(options.config !== undefined ? { config: options.config } : {}),\n    requirePepper: true,\n  });\n  try {\n    if (ctx.pepper === undefined) {\n      throw new Error(\n        '[graphorin/cli] internal: pepper resolution should have populated ctx.pepper',\n      );\n    }\n    const env = options.env ?? 'live';\n    const expiresInMs =\n      options.expiresIn !== undefined ? parseDuration(options.expiresIn) : undefined;\n    const created = await createToken({\n      tokenStore: ctx.store.authTokens,\n      pepper: ctx.pepper,\n      env,\n      scopes: options.scopes,\n      ...(options.label !== undefined ? { label: options.label } : {}),\n      ...(expiresInMs !== undefined ? { expiresInMs } : {}),\n    });\n    const raw = await created.raw.use((s) => String(s));\n    const out: TokenCreateResult = Object.freeze({\n      id: created.record.id,\n      ...(created.record.label !== undefined ? { label: created.record.label } : {}),\n      scopes: Object.freeze([...created.record.scopes]),\n      raw,\n      ...(created.record.expiresAt !== undefined ? { expiresAt: created.record.expiresAt } : {}),\n    });\n    emitReport(options, out, () => {\n      const print = options.print ?? defaultPrintSink;\n      print(brand(`token created (id=${out.id}, scopes=${out.scopes.join(',')})`));\n      print(brand(`raw token (shown ONCE):`));\n      print(`  ${out.raw}`);\n      if (out.expiresAt !== undefined) {\n        print(brand(`expires at: ${out.expiresAt}`));\n      }\n    });\n    return out;\n  } finally {\n    await ctx.close();\n  }\n}\n\n/** @stable */\nexport interface TokenListOptions extends TokenCommonOptions {\n  readonly includeRevoked?: boolean;\n}\n\n/**\n * List token metadata.\n *\n * @stable\n */\nexport async function runTokenList(\n  options: TokenListOptions = {},\n): Promise<ReadonlyArray<TokenMetadata>> {\n  const ctx = await openStoreContext({\n    ...(options.config !== undefined ? { config: options.config } : {}),\n  });\n  try {\n    const list = await listTokens(ctx.store.authTokens, {\n      includeRevoked: options.includeRevoked === true,\n    });\n    emitReport(options, list, () => {\n      const print = options.print ?? defaultPrintSink;\n      if (list.length === 0) {\n        print(brand('no tokens registered.'));\n        return;\n      }\n      print(brand(`${list.length} token(s):`));\n      for (const t of list) {\n        const status = t.revokedAt !== undefined ? statusMarker('warn') : statusMarker('ok');\n        print(`  ${status} ${t.id} (label=${t.label ?? '-'}, scopes=${t.scopes.join(',')})`);\n      }\n    });\n    return list;\n  } finally {\n    await ctx.close();\n  }\n}\n\n/** @stable */\nexport interface TokenRevokeOptions extends TokenCommonOptions {\n  readonly id: string;\n}\n\n/**\n * Revoke a single token.\n *\n * @stable\n */\nexport async function runTokenRevoke(\n  options: TokenRevokeOptions,\n): Promise<TokenMetadata | undefined> {\n  const ctx = await openStoreContext({\n    ...(options.config !== undefined ? { config: options.config } : {}),\n  });\n  try {\n    const result = await revokeToken(ctx.store.authTokens, options.id);\n    emitReport(options, result ?? null, () => {\n      const print = options.print ?? defaultPrintSink;\n      if (result === undefined) {\n        print(brand(`token '${options.id}' not found.`));\n        process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;\n        return;\n      }\n      print(brand(`token '${result.id}' revoked at ${result.revokedAt ?? '<now>'}`));\n    });\n    return result;\n  } finally {\n    await ctx.close();\n  }\n}\n\n/** @stable */\nexport interface TokenRotateOptions extends TokenCommonOptions {\n  readonly id: string;\n  readonly env?: 'live' | 'test';\n}\n\n/**\n * Revoke an existing token and immediately mint a fresh one with the\n * same scopes. Returns the new raw token bytes once.\n *\n * @stable\n */\nexport async function runTokenRotate(options: TokenRotateOptions): Promise<TokenCreateResult> {\n  const ctx = await openStoreContext({\n    ...(options.config !== undefined ? { config: options.config } : {}),\n    requirePepper: true,\n  });\n  try {\n    if (ctx.pepper === undefined) {\n      throw new Error('[graphorin/cli] internal: pepper missing.');\n    }\n    const env = options.env ?? 'live';\n    const result = await rotateToken({\n      tokenStore: ctx.store.authTokens,\n      pepper: ctx.pepper,\n      id: options.id,\n      env,\n    });\n    const raw = await result.next.raw.use((s) => String(s));\n    const out: TokenCreateResult = Object.freeze({\n      id: result.next.record.id,\n      ...(result.next.record.label !== undefined ? { label: result.next.record.label } : {}),\n      scopes: Object.freeze([...result.next.record.scopes]),\n      raw,\n      ...(result.next.record.expiresAt !== undefined\n        ? { expiresAt: result.next.record.expiresAt }\n        : {}),\n    });\n    emitReport(options, out, () => {\n      const print = options.print ?? defaultPrintSink;\n      print(brand(`token '${result.old.id}' revoked + replaced by '${out.id}'`));\n      print(brand('raw token (shown ONCE):'));\n      print(`  ${raw}`);\n    });\n    return out;\n  } finally {\n    await ctx.close();\n  }\n}\n\n/** @stable */\nexport interface TokenRekeyOptions extends TokenCommonOptions {\n  readonly env?: 'live' | 'test';\n}\n\n/**\n * Re-issue every active token. Used after a known compromise.\n *\n * @stable\n */\nexport async function runTokenRekey(\n  options: TokenRekeyOptions = {},\n): Promise<\n  ReadonlyArray<{ readonly oldId: string; readonly newId: string; readonly raw: string }>\n> {\n  const ctx = await openStoreContext({\n    ...(options.config !== undefined ? { config: options.config } : {}),\n    requirePepper: true,\n  });\n  try {\n    if (ctx.pepper === undefined) {\n      throw new Error('[graphorin/cli] internal: pepper missing.');\n    }\n    const result = await rekeyTokens({\n      tokenStore: ctx.store.authTokens,\n      pepper: ctx.pepper,\n      env: options.env ?? 'live',\n    });\n    const out: Array<{ readonly oldId: string; readonly newId: string; readonly raw: string }> = [];\n    for (const [oldId, created] of result) {\n      const raw = await created.raw.use((s) => String(s));\n      out.push(Object.freeze({ oldId, newId: created.record.id, raw }));\n    }\n    const frozen = Object.freeze(out);\n    emitReport(options, frozen, () => {\n      const print = options.print ?? defaultPrintSink;\n      print(brand(`rekeyed ${frozen.length} token(s):`));\n      for (const row of frozen) {\n        print(`  - old=${row.oldId} new=${row.newId}`);\n        print(`    raw: ${row.raw}`);\n      }\n    });\n    return frozen;\n  } finally {\n    await ctx.close();\n  }\n}\n\n/** @stable */\nexport interface TokenVerifyOptions extends CommonOutputOptions {\n  readonly token: string;\n  /** Optional override of the expected token prefix. */\n  readonly prefix?: string;\n}\n\n/** @stable */\nexport interface TokenVerifyResult {\n  readonly ok: boolean;\n  readonly reason?: string;\n}\n\n/**\n * Offline checksum verification. Confirms the structural shape, the\n * environment marker, and the CRC checksum but does NOT consult the\n * token store — it only proves the token was minted by a Graphorin\n * helper.\n *\n * @stable\n */\nexport function runTokenVerify(options: TokenVerifyOptions): TokenVerifyResult {\n  const result = verifyOffline(options.token, {\n    ...(options.prefix !== undefined ? { acceptPrefix: options.prefix } : {}),\n  });\n  const out: TokenVerifyResult = Object.freeze({\n    ok: result.ok,\n    ...(result.ok ? {} : { reason: result.reason }),\n  });\n  emitReport(options, out, () => {\n    const print = options.print ?? defaultPrintSink;\n    if (out.ok) {\n      print(brand(`token format ${statusMarker('ok')} (offline checksum verified)`));\n      return;\n    }\n    print(brand(`token format ${statusMarker('fail')} (${out.reason ?? 'unknown reason'})`));\n    process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;\n  });\n  return out;\n}\n\n/**\n * Tiny duration parser. Accepts `Ns`, `Nm`, `Nh`, `Nd`. Returns\n * milliseconds. Throws on invalid input — surfaced as a fail-fast at\n * the CLI boundary.\n *\n * @internal\n */\nexport function parseDuration(input: string): number {\n  const match = /^(\\d+)\\s*([smhd])$/i.exec(input.trim());\n  if (!match) {\n    throw new Error(\n      `[graphorin/cli] invalid --expires-in '${input}'. Use the form '<number><s|m|h|d>' (e.g. 30d).`,\n    );\n  }\n  const value = Number.parseInt(match[1] as string, 10);\n  const unit = (match[2] as string).toLowerCase();\n  switch (unit) {\n    case 's':\n      return value * 1000;\n    case 'm':\n      return value * 60_000;\n    case 'h':\n      return value * 60 * 60_000;\n    case 'd':\n      return value * ONE_DAY_MS;\n    default:\n      throw new Error(`[graphorin/cli] invalid --expires-in unit '${unit}'.`);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,MAAM,aAAa,OAAU,KAAK;;;;;;AA+BlC,eAAsB,eAAe,SAAyD;CAC5F,MAAM,MAAM,MAAM,iBAAiB;EACjC,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,QAAQ,GAAG,EAAE;EAClE,eAAe;EAChB,CAAC;AACF,KAAI;AACF,MAAI,IAAI,WAAW,OACjB,OAAM,IAAI,MACR,+EACD;EAEH,MAAM,MAAM,QAAQ,OAAO;EAC3B,MAAM,cACJ,QAAQ,cAAc,SAAY,cAAc,QAAQ,UAAU,GAAG;EACvE,MAAM,UAAU,MAAM,YAAY;GAChC,YAAY,IAAI,MAAM;GACtB,QAAQ,IAAI;GACZ;GACA,QAAQ,QAAQ;GAChB,GAAI,QAAQ,UAAU,SAAY,EAAE,OAAO,QAAQ,OAAO,GAAG,EAAE;GAC/D,GAAI,gBAAgB,SAAY,EAAE,aAAa,GAAG,EAAE;GACrD,CAAC;EACF,MAAM,MAAM,MAAM,QAAQ,IAAI,KAAK,MAAM,OAAO,EAAE,CAAC;EACnD,MAAMA,MAAyB,OAAO,OAAO;GAC3C,IAAI,QAAQ,OAAO;GACnB,GAAI,QAAQ,OAAO,UAAU,SAAY,EAAE,OAAO,QAAQ,OAAO,OAAO,GAAG,EAAE;GAC7E,QAAQ,OAAO,OAAO,CAAC,GAAG,QAAQ,OAAO,OAAO,CAAC;GACjD;GACA,GAAI,QAAQ,OAAO,cAAc,SAAY,EAAE,WAAW,QAAQ,OAAO,WAAW,GAAG,EAAE;GAC1F,CAAC;AACF,aAAW,SAAS,WAAW;GAC7B,MAAM,QAAQ,QAAQ,SAAS;AAC/B,SAAM,MAAM,qBAAqB,IAAI,GAAG,WAAW,IAAI,OAAO,KAAK,IAAI,CAAC,GAAG,CAAC;AAC5E,SAAM,MAAM,0BAA0B,CAAC;AACvC,SAAM,KAAK,IAAI,MAAM;AACrB,OAAI,IAAI,cAAc,OACpB,OAAM,MAAM,eAAe,IAAI,YAAY,CAAC;IAE9C;AACF,SAAO;WACC;AACR,QAAM,IAAI,OAAO;;;;;;;;AAcrB,eAAsB,aACpB,UAA4B,EAAE,EACS;CACvC,MAAM,MAAM,MAAM,iBAAiB,EACjC,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,QAAQ,GAAG,EAAE,EACnE,CAAC;AACF,KAAI;EACF,MAAM,OAAO,MAAM,WAAW,IAAI,MAAM,YAAY,EAClD,gBAAgB,QAAQ,mBAAmB,MAC5C,CAAC;AACF,aAAW,SAAS,YAAY;GAC9B,MAAM,QAAQ,QAAQ,SAAS;AAC/B,OAAI,KAAK,WAAW,GAAG;AACrB,UAAM,MAAM,wBAAwB,CAAC;AACrC;;AAEF,SAAM,MAAM,GAAG,KAAK,OAAO,YAAY,CAAC;AACxC,QAAK,MAAM,KAAK,KAEd,OAAM,KADS,EAAE,cAAc,SAAY,aAAa,OAAO,GAAG,aAAa,KAAK,CAClE,GAAG,EAAE,GAAG,UAAU,EAAE,SAAS,IAAI,WAAW,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG;IAEtF;AACF,SAAO;WACC;AACR,QAAM,IAAI,OAAO;;;;;;;;AAcrB,eAAsB,eACpB,SACoC;CACpC,MAAM,MAAM,MAAM,iBAAiB,EACjC,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,QAAQ,GAAG,EAAE,EACnE,CAAC;AACF,KAAI;EACF,MAAM,SAAS,MAAM,YAAY,IAAI,MAAM,YAAY,QAAQ,GAAG;AAClE,aAAW,SAAS,UAAU,YAAY;GACxC,MAAM,QAAQ,QAAQ,SAAS;AAC/B,OAAI,WAAW,QAAW;AACxB,UAAM,MAAM,UAAU,QAAQ,GAAG,cAAc,CAAC;AAChD,YAAQ,WAAW,WAAW;AAC9B;;AAEF,SAAM,MAAM,UAAU,OAAO,GAAG,eAAe,OAAO,aAAa,UAAU,CAAC;IAC9E;AACF,SAAO;WACC;AACR,QAAM,IAAI,OAAO;;;;;;;;;AAgBrB,eAAsB,eAAe,SAAyD;CAC5F,MAAM,MAAM,MAAM,iBAAiB;EACjC,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,QAAQ,GAAG,EAAE;EAClE,eAAe;EAChB,CAAC;AACF,KAAI;AACF,MAAI,IAAI,WAAW,OACjB,OAAM,IAAI,MAAM,4CAA4C;EAE9D,MAAM,MAAM,QAAQ,OAAO;EAC3B,MAAM,SAAS,MAAM,YAAY;GAC/B,YAAY,IAAI,MAAM;GACtB,QAAQ,IAAI;GACZ,IAAI,QAAQ;GACZ;GACD,CAAC;EACF,MAAM,MAAM,MAAM,OAAO,KAAK,IAAI,KAAK,MAAM,OAAO,EAAE,CAAC;EACvD,MAAMA,MAAyB,OAAO,OAAO;GAC3C,IAAI,OAAO,KAAK,OAAO;GACvB,GAAI,OAAO,KAAK,OAAO,UAAU,SAAY,EAAE,OAAO,OAAO,KAAK,OAAO,OAAO,GAAG,EAAE;GACrF,QAAQ,OAAO,OAAO,CAAC,GAAG,OAAO,KAAK,OAAO,OAAO,CAAC;GACrD;GACA,GAAI,OAAO,KAAK,OAAO,cAAc,SACjC,EAAE,WAAW,OAAO,KAAK,OAAO,WAAW,GAC3C,EAAE;GACP,CAAC;AACF,aAAW,SAAS,WAAW;GAC7B,MAAM,QAAQ,QAAQ,SAAS;AAC/B,SAAM,MAAM,UAAU,OAAO,IAAI,GAAG,2BAA2B,IAAI,GAAG,GAAG,CAAC;AAC1E,SAAM,MAAM,0BAA0B,CAAC;AACvC,SAAM,KAAK,MAAM;IACjB;AACF,SAAO;WACC;AACR,QAAM,IAAI,OAAO;;;;;;;;AAcrB,eAAsB,cACpB,UAA6B,EAAE,EAG/B;CACA,MAAM,MAAM,MAAM,iBAAiB;EACjC,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,QAAQ,GAAG,EAAE;EAClE,eAAe;EAChB,CAAC;AACF,KAAI;AACF,MAAI,IAAI,WAAW,OACjB,OAAM,IAAI,MAAM,4CAA4C;EAE9D,MAAM,SAAS,MAAM,YAAY;GAC/B,YAAY,IAAI,MAAM;GACtB,QAAQ,IAAI;GACZ,KAAK,QAAQ,OAAO;GACrB,CAAC;EACF,MAAMC,MAAuF,EAAE;AAC/F,OAAK,MAAM,CAAC,OAAO,YAAY,QAAQ;GACrC,MAAM,MAAM,MAAM,QAAQ,IAAI,KAAK,MAAM,OAAO,EAAE,CAAC;AACnD,OAAI,KAAK,OAAO,OAAO;IAAE;IAAO,OAAO,QAAQ,OAAO;IAAI;IAAK,CAAC,CAAC;;EAEnE,MAAM,SAAS,OAAO,OAAO,IAAI;AACjC,aAAW,SAAS,cAAc;GAChC,MAAM,QAAQ,QAAQ,SAAS;AAC/B,SAAM,MAAM,WAAW,OAAO,OAAO,YAAY,CAAC;AAClD,QAAK,MAAM,OAAO,QAAQ;AACxB,UAAM,WAAW,IAAI,MAAM,OAAO,IAAI,QAAQ;AAC9C,UAAM,YAAY,IAAI,MAAM;;IAE9B;AACF,SAAO;WACC;AACR,QAAM,IAAI,OAAO;;;;;;;;;;;AAyBrB,SAAgB,eAAe,SAAgD;CAC7E,MAAM,SAAS,cAAc,QAAQ,OAAO,EAC1C,GAAI,QAAQ,WAAW,SAAY,EAAE,cAAc,QAAQ,QAAQ,GAAG,EAAE,EACzE,CAAC;CACF,MAAMC,MAAyB,OAAO,OAAO;EAC3C,IAAI,OAAO;EACX,GAAI,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,OAAO,QAAQ;EAC/C,CAAC;AACF,YAAW,SAAS,WAAW;EAC7B,MAAM,QAAQ,QAAQ,SAAS;AAC/B,MAAI,IAAI,IAAI;AACV,SAAM,MAAM,gBAAgB,aAAa,KAAK,CAAC,8BAA8B,CAAC;AAC9E;;AAEF,QAAM,MAAM,gBAAgB,aAAa,OAAO,CAAC,IAAI,IAAI,UAAU,iBAAiB,GAAG,CAAC;AACxF,UAAQ,WAAW,WAAW;GAC9B;AACF,QAAO;;;;;;;;;AAUT,SAAgB,cAAc,OAAuB;CACnD,MAAM,QAAQ,sBAAsB,KAAK,MAAM,MAAM,CAAC;AACtD,KAAI,CAAC,MACH,OAAM,IAAI,MACR,yCAAyC,MAAM,iDAChD;CAEH,MAAM,QAAQ,OAAO,SAAS,MAAM,IAAc,GAAG;CACrD,MAAM,OAAQ,MAAM,GAAc,aAAa;AAC/C,SAAQ,MAAR;EACE,KAAK,IACH,QAAO,QAAQ;EACjB,KAAK,IACH,QAAO,QAAQ;EACjB,KAAK,IACH,QAAO,QAAQ,KAAK;EACtB,KAAK,IACH,QAAO,QAAQ;EACjB,QACE,OAAM,IAAI,MAAM,8CAA8C,KAAK,IAAI"}

package/dist/commands/tools-lint.d.ts

@@ -0,0 +1,103 @@
+import { CommonOutputOptions } from "../internal/output.js";
+import { LintFinding, LintFindingKind } from "@graphorin/eslint-plugin";
+
+//#region src/commands/tools-lint.d.ts
+
+/**
+ * Counter event emitted per below-threshold tool per invocation. The
+ * CLI exposes a configurable sink so observability pipelines (Phase
+ * 04) can wire the counter into Prometheus / OTLP without touching
+ * the CLI runtime. Default: no-op.
+ *
+ * Mirrors the `tool.lint.threshold.violations.total{toolName,score,
+ * threshold}` contract documented in RB-49 § Counter emission.
+ *
+ * @stable
+ */
+interface ToolsLintThresholdViolation {
+  readonly toolName: string;
+  readonly score: number;
+  readonly threshold: number;
+}
+/** @stable */
+type ToolsLintCounterSink = (event: ToolsLintThresholdViolation) => void;
+/** @stable */
+interface ToolsLintOptions extends CommonOutputOptions {
+  /** Optional path to a `tsconfig.json` whose `include` overrides the file glob. */
+  readonly config?: string;
+  /** Minimum acceptable per-tool score. Default `60`. */
+  readonly threshold?: number;
+  /** Output format. Default `'text'`. */
+  readonly format?: 'text' | 'json';
+  /** Optional override of the file glob pattern. */
+  readonly source?: string;
+  /** Override `cwd`. Default `process.cwd()`. */
+  readonly cwd?: string;
+  /**
+   * Test seam — supply a list of `(file, source)` pairs directly so
+   * the test does not need to fish around the filesystem.
+   */
+  readonly inlineSources?: ReadonlyArray<{
+    readonly file: string;
+    readonly source: string;
+  }>;
+  /**
+   * Optional sink for the `tool.lint.threshold.violations.total`
+   * counter (RB-49). The CLI calls this once per below-threshold tool
+   * per invocation. Default: no-op.
+   */
+  readonly counterSink?: ToolsLintCounterSink;
+}
+/**
+ * Documented JSON shape emitted on `--format json`. The shape is
+ * stable + forward-compatible with the `@eslint/mcp` industry
+ * direction (per-finding `rule` / `severity` / `message` / `location`
+ * mirror the ESLint LSP convention).
+ *
+ * @stable
+ */
+interface ToolsLintReport {
+  readonly summary: {
+    readonly totalTools: number;
+    readonly totalFindings: number;
+    readonly threshold: number;
+    readonly passed: number;
+    readonly failed: number;
+  };
+  readonly tools: ReadonlyArray<ToolsLintReportTool>;
+}
+/** @stable */
+interface ToolsLintReportTool {
+  readonly name: string;
+  readonly source: string;
+  readonly score: number;
+  readonly axes: {
+    readonly description: number;
+    readonly examples: number;
+    readonly parameterNaming: number;
+  };
+  readonly findings: ReadonlyArray<ToolsLintReportFinding>;
+}
+/** @stable */
+interface ToolsLintReportFinding {
+  readonly rule: LintFinding['rule'];
+  readonly kind: LintFindingKind;
+  readonly severity: LintFinding['severity'];
+  readonly message: string;
+  readonly location: {
+    readonly file: string;
+    readonly line: number;
+  };
+  readonly hint?: string;
+  readonly matchedPattern?: string;
+}
+/**
+ * Run the discovery + grader pipeline. Returns the structured report
+ * the CLI emits to stdout.
+ *
+ * @stable
+ */
+declare function runToolsLint(options?: ToolsLintOptions): Promise<ToolsLintReport>;
+//#endregion
+export { ToolsLintOptions, ToolsLintReport, runToolsLint };
+//# sourceMappingURL=tools-lint.d.ts.map

package/dist/commands/tools-lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-lint.d.ts","names":[],"sources":["../../src/commands/tools-lint.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;UA0EiB,2BAAA;;;;;;KAOL,oBAAA,WAA+B;;UAG1B,gBAAA,SAAyB;;;;;;;;;;;;;;;2BAef;;;;;;;;;yBAMF;;;;;;;;;;UAWR,eAAA;;;;;;;;kBAQC,cAAc;;;UAIf,mBAAA;;;;;;;;;qBASI,cAAc;;;UAIlB,sBAAA;iBACA;iBACA;qBACI;;;;;;;;;;;;;;;iBAgBC,YAAA,WAAsB,mBAAwB,QAAQ"}