@hardfin/cli 0.0.2-dev.13 → 0.0.2-dev.15

package/README.md

@@ -285,9 +285,9 @@ Nothing secret is printed. An API key and a refresh token are each reported as a
 `sha256:` fingerprint, which identifies a credential across two machines without disclosing
 it.
 
-`refreshExpiresAt` is an estimate. Hardfin expires an unused refresh token after 90 days,
-but the token endpoint reports no expiry, so the CLI applies that rule to the date it last
-renewed. The flag `refreshExpiryIsEstimated` says so in the output.
+`refreshExpiresAt` is what the server said when it issued the token. A sign in stored before
+the server reported one falls back to Hardfin's 90-day rule, and `refreshExpiryIsEstimated`
+says which of the two you are looking at.
 
 ## Local configuration
 

package/dist/cli.js

@@ -4,10 +4,10 @@ import { Command, Option } from "commander";
 import { z } from "zod";
 import { chmodSync, closeSync, existsSync, mkdirSync, openAsBlob, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { arch, cpus, homedir, release, totalmem, type, version } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
 import { createServer } from "node:http";
-import { createHash, randomBytes } from "node:crypto";
 import { createInterface } from "node:readline";
 //#region src/command/registry.ts
 /** ExitCode is what the process returns, and what an agent branches on. */
@@ -252,6 +252,32 @@ function toSummary(command) {
 	};
 }
 //#endregion
+//#region src/auth/jwt.ts
+/**
+* toClaims reads an access token's payload for display. Nothing here verifies the
+* signature, because the API is what decides whether a token is good.
+*/
+function toClaims(token) {
+	const payload = token.split(".")[1];
+	if (!payload) return {};
+	try {
+		const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+		return {
+			expiresAt: typeof decoded["exp"] === "number" ? decoded["exp"] * 1e3 : void 0,
+			issuedAt: typeof decoded["iat"] === "number" ? decoded["iat"] * 1e3 : void 0,
+			scopes: toScopes(decoded),
+			subject: typeof decoded["sub"] === "string" ? decoded["sub"] : void 0
+		};
+	} catch {
+		return {};
+	}
+}
+/** toScopes reads scp, which is where Hardfin puts an access token's scopes. */
+function toScopes(decoded) {
+	if (Array.isArray(decoded["scp"])) return decoded["scp"].map(String);
+	return typeof decoded["scope"] === "string" ? decoded["scope"].split(" ") : void 0;
+}
+//#endregion
 //#region src/auth/metadata.ts
 const METADATA_PATH = "/.well-known/oauth-authorization-server";
 const AuthorizationServerMetadata = z.looseObject({
@@ -293,6 +319,7 @@ const TokenResponse = z.looseObject({
 	token_type: z.string(),
 	expires_in: z.number().optional(),
 	refresh_token: z.string().optional(),
+	refresh_token_expires_in: z.number().optional(),
 	scope: z.string().optional()
 });
 /** GrantFailure is a token request the authorization server refused. */
@@ -351,6 +378,7 @@ async function toTokens(url, form) {
 	return {
 		accessToken: parsed.data.access_token,
 		refreshToken: parsed.data.refresh_token,
+		refreshExpiresAt: parsed.data.refresh_token_expires_in === void 0 ? void 0 : Date.now() + parsed.data.refresh_token_expires_in * 1e3,
 		scope: parsed.data.scope,
 		expiresAt: parsed.data.expires_in === void 0 ? void 0 : Date.now() + parsed.data.expires_in * 1e3
 	};
@@ -375,40 +403,55 @@ function toCredentialPath() {
 * family lifetime runs from. Callers hold the credential lock, which is what makes a write
 * from another process merge rather than disappear.
 */
-function keep(issuer, refreshToken) {
+function keep(issuer, refreshToken, expiresAt) {
 	const now = (/* @__PURE__ */ new Date()).toISOString();
 	const record = {
 		refreshToken,
 		signedInAt: toCredential(issuer)?.signedInAt ?? now,
-		renewedAt: now
+		renewedAt: now,
+		expiresAt: expiresAt === void 0 ? void 0 : new Date(expiresAt).toISOString()
 	};
 	const keyring = toKeyring(issuer);
 	if (keyring) try {
 		keyring.setPassword(JSON.stringify(record));
+		forgetFile(issuer);
 		return "keyring";
 	} catch {}
 	writeFile({
 		...readFile(),
 		[issuer]: record
 	});
+	forgetKeyring(issuer);
 	return "file";
 }
-/** toCredential reads what is held for an issuer, and where it was held. */
+/**
+* toCredential reads what is held for an issuer, and where it was held. Both backends are
+* read, because a host that lost its keyring for a while wrote to the file instead, and the
+* newer of the two is the one the server has not spent.
+*/
 function toCredential(issuer) {
-	const keyring = toKeyring(issuer);
-	if (keyring) try {
-		const held = keyring.getPassword();
-		if (held) return {
-			...toRecord(held),
-			backend: "keyring"
-		};
-	} catch {}
+	const fromKeyring = toKeyringCredential(issuer);
 	const held = readFile()[issuer];
-	return held === void 0 ? void 0 : {
+	const fromFile = held === void 0 ? void 0 : {
 		...held,
 		backend: "file",
 		path: toCredentialPath()
 	};
+	if (!fromKeyring || !fromFile) return fromKeyring ?? fromFile;
+	return (fromFile.renewedAt ?? "") > (fromKeyring.renewedAt ?? "") ? fromFile : fromKeyring;
+}
+function toKeyringCredential(issuer) {
+	const keyring = toKeyring(issuer);
+	if (!keyring) return;
+	try {
+		const held = keyring.getPassword();
+		return held ? {
+			...toRecord(held),
+			backend: "keyring"
+		} : void 0;
+	} catch {
+		return;
+	}
 }
 /** toRecord reads a stored entry, which older versions wrote as the bare token. */
 function toRecord(held) {
@@ -421,10 +464,17 @@ function toRecord(held) {
 }
 /** forget removes whatever is held for an issuer, in both places. */
 function forget(issuer) {
+	forgetKeyring(issuer);
+	forgetFile(issuer);
+}
+function forgetKeyring(issuer) {
 	const keyring = toKeyring(issuer);
-	if (keyring) try {
+	if (!keyring) return;
+	try {
 		keyring.deletePassword();
 	} catch {}
+}
+function forgetFile(issuer) {
 	const held = readFile();
 	if (held[issuer] === void 0) return;
 	delete held[issuer];
@@ -471,6 +521,8 @@ const STALE_MS = 3e4;
 const WAIT_MS$1 = 1e4;
 const RETRY_MS = 25;
 const DIRECTORY_MODE = 448;
+/** What this process wrote into the lock, which is how it knows the lock is still its own. */
+let heldBy;
 /** toLockPath names the lock every process coordinates credential writes through. */
 function toLockPath() {
 	return join(dirname(toCredentialPath()), "credentials.lock");
@@ -482,17 +534,23 @@ function tryAcquire() {
 		recursive: true,
 		mode: DIRECTORY_MODE
 	});
+	const mark = `${process.pid}:${randomUUID()}`;
 	try {
 		const handle = openSync(path, "wx");
-		writeSync(handle, String(process.pid));
+		writeSync(handle, mark);
 		closeSync(handle);
+		heldBy = mark;
 		return true;
 	} catch {
-		return isStale(path) ? steal(path) : false;
+		return isStale(path) ? steal(path, mark) : false;
 	}
 }
-/** release lets the next process in. */
+/** release lets the next process in, and only ever removes this process's own lock. */
 function release$1() {
+	const mark = heldBy;
+	if (mark === void 0) return;
+	heldBy = void 0;
+	if (toMark(toLockPath()) !== mark) return;
 	rmSync(toLockPath(), { force: true });
 }
 /**
@@ -519,9 +577,29 @@ function isStale(path) {
 		return true;
 	}
 }
-function steal(path) {
+/**
+* steal takes over a lock whose holder is gone. Two processes can reach this at once, so
+* the winner is whichever mark survives in the file, not whichever removed it.
+*/
+function steal(path, mark) {
 	rmSync(path, { force: true });
-	return tryAcquire();
+	try {
+		const handle = openSync(path, "wx");
+		writeSync(handle, mark);
+		closeSync(handle);
+	} catch {
+		return false;
+	}
+	if (toMark(path) !== mark) return false;
+	heldBy = mark;
+	return true;
+}
+function toMark(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return;
+	}
 }
 //#endregion
 //#region src/auth/session.ts
@@ -564,9 +642,9 @@ async function toAccessToken(settings, refreshToken) {
 	return await withLock(async () => {
 		const latest = toCredential(settings.issuerUrl)?.refreshToken ?? refreshToken;
 		try {
-			const tokens = await toTokensFromRefresh(metadata.token_endpoint, settings.clientId, latest);
+			const tokens = toDated(await toTokensFromRefresh(metadata.token_endpoint, settings.clientId, latest));
 			held.set(settings.issuerUrl, tokens);
-			if (tokens.refreshToken && tokens.refreshToken !== latest) keep(settings.issuerUrl, tokens.refreshToken);
+			store(settings.issuerUrl, tokens, latest);
 			return tokens;
 		} catch (error) {
 			if (error instanceof GrantFailure && isDead(error.code)) {
@@ -577,14 +655,37 @@ async function toAccessToken(settings, refreshToken) {
 		}
 	});
 }
-/** Codes the authorization server uses when a refresh token can never work again. */
-const DEAD_GRANT_CODES = /* @__PURE__ */ new Set([
-	"invalid_grant",
-	"invalid_client",
-	"unauthorized_client"
-]);
+/**
+* invalid_grant is the only refusal that says anything about the refresh token itself.
+* invalid_client and unauthorized_client describe the client registration, which is server
+* configuration and a setting a person can mistype, so a good credential survives them.
+*/
 function isDead(code) {
-	return DEAD_GRANT_CODES.has(code);
+	return code === "invalid_grant";
+}
+/**
+* toDated fills in when an access token expires. A token endpoint that states no expires_in
+* would otherwise have this process refresh on every command, and every refresh spends a
+* generation of the token family.
+*/
+function toDated(tokens) {
+	if (tokens.expiresAt !== void 0) return tokens;
+	return {
+		...tokens,
+		expiresAt: toClaims(tokens.accessToken).expiresAt
+	};
+}
+/**
+* store writes what a rotation issued. The old token is spent either way, so failing to
+* write the new one is worth saying out loud rather than failing a command that succeeded.
+*/
+function store(issuer, tokens, previous) {
+	if (!tokens.refreshToken || tokens.refreshToken === previous) return;
+	try {
+		keep(issuer, tokens.refreshToken, tokens.refreshExpiresAt);
+	} catch (error) {
+		process.stderr.write(`warning: this sign in was renewed but could not be stored, so the next command will ask you to sign in again: ${error instanceof Error ? error.message : String(error)}\n`);
+	}
 }
 /** forgetHeldTokens drops the access tokens this process is holding. */
 function forgetHeldTokens() {
@@ -1194,6 +1295,7 @@ function toPrompt(url) {
 		fail = reject;
 	});
 	const input = process.stdin;
+	pasted.catch(() => {});
 	if (!input.isTTY) return {
 		pasted,
 		close: () => {}
@@ -1309,9 +1411,13 @@ async function runLogin(input) {
 		process.stderr.write(opened ? `Opening your browser to sign in. If it did not open:\n\n${url}\n\n` : `Open this URL to sign in:\n\n${url}\n\n`);
 		const prompt = toPrompt(url);
 		if (process.stdin.isTTY) process.stderr.write("Press c to copy the URL, or paste the code or redirect URL here: ");
-		const callback = await Promise.race([listener.callback, prompt.pasted]);
-		listener.close();
-		prompt.close();
+		let callback;
+		try {
+			callback = await Promise.race([listener.callback, prompt.pasted]);
+		} finally {
+			listener.close();
+			prompt.close();
+		}
 		process.stderr.write(callback.error ? "\n" : "\nApproved, finishing the sign in\n");
 		if (callback.error) {
 			writeFailure(`sign in was refused: ${callback.error}${callback.errorDescription ? `, ${callback.errorDescription}` : ""}`, input.isJSON);
@@ -1357,7 +1463,15 @@ async function runDeviceLogin(input, metadata, scope) {
 		opened ? "Opened your browser there. Waiting for approval\n" : "Open that page on any machine, and enter the code. Waiting for approval\n"
 	].join("\n"));
 	const prompt = toPrompt(url);
-	return await toSignedIn(input, metadata, await toTokensFromDevice(metadata.token_endpoint, settings.clientId, device).finally(() => prompt.close()));
+	try {
+		return await toSignedIn(input, metadata, await Promise.race([toTokensFromDevice(metadata.token_endpoint, settings.clientId, device), prompt.pasted.then(toCancelled)]));
+	} finally {
+		prompt.close();
+	}
+}
+/** toCancelled ends a device sign in that the keyboard interrupted. */
+function toCancelled() {
+	throw new Error("sign in was cancelled");
 }
 /** toSignedIn stores what a sign in issued, whichever flow issued it. */
 async function toSignedIn(input, metadata, tokens) {
@@ -1366,7 +1480,7 @@ async function toSignedIn(input, metadata, tokens) {
 		writeFailure("the authorization server issued no refresh token, so this sign in cannot be kept", input.isJSON);
 		return ExitCode.ERROR;
 	}
-	const backend = await withLock(() => keep(input.resolved.settings.issuerUrl, refreshToken));
+	const backend = await withLock(() => keep(input.resolved.settings.issuerUrl, refreshToken, tokens.refreshExpiresAt));
 	if (input.isJSON) {
 		writeData({
 			signedIn: true,
@@ -1632,6 +1746,13 @@ async function runMcp(input) {
 }
 //#endregion
 //#region src/command/operation.ts
+/**
+* toEnum takes a value in any case, as the API does, and answers the spelling the document
+* lists, which is what a response always uses.
+*/
+function toEnum(values) {
+	return z.string().transform((value) => values.find((allowed) => allowed.toLowerCase() === value.toLowerCase()) ?? value).pipe(z.enum(values));
+}
 const UNSET_FLAG = {
 	name: "unset",
 	description: "A field to clear, named as its flag is, repeatable",
@@ -1738,7 +1859,9 @@ function toQuery(operation, flags) {
 	for (const flag of operation.queryFlags) {
 		const value = flags[toOptionKey(flag.name)];
 		if (value === void 0) continue;
-		for (const entry of Array.isArray(value) ? value : [value]) query.append(flag.queryName, String(entry));
+		const parsed = flag.schema.safeParse(value);
+		const carried = parsed.success ? parsed.data : value;
+		for (const entry of Array.isArray(carried) ? carried : [carried]) query.append(flag.queryName, String(entry));
 	}
 	return query;
 }
@@ -1758,7 +1881,10 @@ async function toForm(upload, flags) {
 	}
 	for (const field of upload.fields) {
 		const value = flags[toOptionKey(field.name)];
-		if (value !== void 0) form.append(field.jsonPath[0] ?? field.name, String(value));
+		if (value !== void 0) {
+			const parsed = field.schema.safeParse(value);
+			form.append(field.jsonPath[0] ?? field.name, String(parsed.success ? parsed.data : value));
+		}
 	}
 	return form;
 }
@@ -1844,21 +1970,21 @@ const surfaceCommands = [
 						queryName: "page",
 						description: "The page to return, starting at 1",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int()
 					},
 					{
 						name: "limit",
 						queryName: "limit",
 						description: "The number of records per page, from 1 to 100",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int().min(1).max(100)
 					},
 					{
 						name: "sort-by",
 						queryName: "sortBy",
 						description: "The field to sort by",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"serial",
 							"project",
 							"item",
@@ -1872,14 +1998,14 @@ const surfaceCommands = [
 						queryName: "sortOrder",
 						description: "The sort direction",
 						valueName: "value",
-						schema: z.enum(["ASC", "DESC"])
+						schema: toEnum(["ASC", "DESC"])
 					},
 					{
 						name: "archived",
 						queryName: "archived",
 						description: "Whether to return unarchived records, archived records, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -1946,7 +2072,7 @@ const surfaceCommands = [
 						description: "The functional statuses to list, where SCRAPPED lists scrapped assets",
 						valueName: "value",
 						repeatable: true,
-						schema: z.array(z.enum([
+						schema: z.array(toEnum([
 							"FUNCTIONAL",
 							"NEEDS_REVIEW",
 							"NON-FUNCTIONAL",
@@ -1959,7 +2085,7 @@ const surfaceCommands = [
 						description: "The transit statuses to list",
 						valueName: "value",
 						repeatable: true,
-						schema: z.array(z.enum([
+						schema: z.array(toEnum([
 							"IN_TRANSIT",
 							"IN_TRANSIT_TO_FIELD",
 							"IN_TRANSIT_TO_INVENTORY",
@@ -2011,7 +2137,7 @@ const surfaceCommands = [
 						queryName: "scrapped",
 						description: "Whether to list unscrapped assets, scrapped assets, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -2050,7 +2176,7 @@ const surfaceCommands = [
 						jsonPath: ["depreciationModel"],
 						description: "The method one unit is depreciated by, or null to clear it",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"DOUBLE_DECLINING",
 							"STRAIGHT_LINE",
 							"SUM_YEAR",
@@ -2095,7 +2221,7 @@ const surfaceCommands = [
 						description: "The asset's starting functional status, FUNCTIONAL when absent, which cannot be SCRAPPED",
 						valueName: "value",
 						nullable: true,
-						schema: z.enum([
+						schema: toEnum([
 							"FUNCTIONAL",
 							"NEEDS_REVIEW",
 							"NON-FUNCTIONAL",
@@ -2194,7 +2320,7 @@ const surfaceCommands = [
 						description: "The number of months one unit is depreciated over, or null to clear it",
 						valueName: "number",
 						nullable: true,
-						schema: z.coerce.number()
+						schema: z.coerce.number().int()
 					}
 				]
 			}),
@@ -2308,7 +2434,7 @@ const surfaceCommands = [
 						description: "The asset's new functional status, which cannot be SCRAPPED because scrapping has its own endpoint",
 						valueName: "value",
 						nullable: true,
-						schema: z.enum([
+						schema: toEnum([
 							"FUNCTIONAL",
 							"NEEDS_REVIEW",
 							"NON-FUNCTIONAL",
@@ -2390,7 +2516,7 @@ const surfaceCommands = [
 							jsonPath: ["depreciationModel"],
 							description: "The method one unit is depreciated by, or null to clear it",
 							valueName: "value",
-							schema: z.enum([
+							schema: toEnum([
 								"DOUBLE_DECLINING",
 								"STRAIGHT_LINE",
 								"SUM_YEAR",
@@ -2490,7 +2616,7 @@ const surfaceCommands = [
 							description: "The number of months one unit is depreciated over, or null to clear it",
 							valueName: "number",
 							nullable: true,
-							schema: z.coerce.number()
+							schema: z.coerce.number().int()
 						}
 					]
 				}), {
@@ -2546,7 +2672,7 @@ const surfaceCommands = [
 							description: "Whether the adjustment adds to the asset's cost basis or writes it down",
 							valueName: "value",
 							required: true,
-							schema: z.enum(["CAPITALIZATION", "IMPAIRMENT"])
+							schema: toEnum(["CAPITALIZATION", "IMPAIRMENT"])
 						},
 						{
 							name: "amount",
@@ -2578,7 +2704,7 @@ const surfaceCommands = [
 							description: "Why the adjustment was made, which must be one its adjustment type allows",
 							valueName: "value",
 							required: true,
-							schema: z.enum([
+							schema: toEnum([
 								"ADDITION",
 								"BETTERMENT",
 								"DAMAGE",
@@ -3041,7 +3167,7 @@ const surfaceCommands = [
 							description: "Why the useful life was revised",
 							valueName: "value",
 							required: true,
-							schema: z.enum([
+							schema: toEnum([
 								"CHANGE_IN_USE",
 								"DAMAGE",
 								"OBSOLESCENCE",
@@ -3057,7 +3183,7 @@ const surfaceCommands = [
 							description: "The asset's revised useful life in months",
 							valueName: "number",
 							required: true,
-							schema: z.coerce.number()
+							schema: z.coerce.number().int()
 						}
 					]
 				})]
@@ -3084,14 +3210,14 @@ const surfaceCommands = [
 						queryName: "page",
 						description: "The page to return, starting at 1",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int()
 					},
 					{
 						name: "limit",
 						queryName: "limit",
 						description: "The number of records per page, from 1 to 100",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int().min(1).max(100)
 					},
 					{
 						name: "sort-by",
@@ -3105,14 +3231,14 @@ const surfaceCommands = [
 						queryName: "sortOrder",
 						description: "The sort direction",
 						valueName: "value",
-						schema: z.enum(["ASC", "DESC"])
+						schema: toEnum(["ASC", "DESC"])
 					},
 					{
 						name: "archived",
 						queryName: "archived",
 						description: "Whether to return unarchived records, archived records, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -3389,8 +3515,7 @@ const surfaceCommands = [
 						name: "is-public",
 						jsonPath: ["isPublic"],
 						description: "Whether any organization's API key may download the file, which is false unless sent as true",
-						valueName: "value",
-						schema: z.string()
+						schema: z.boolean()
 					}
 				]
 			}
@@ -3434,7 +3559,7 @@ const surfaceCommands = [
 						queryName: "type",
 						description: "The item type to list, SERVICE, DEVICE, or BULK, or absent for every type",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"BULK",
 							"DEVICE",
 							"SERVICE"
@@ -3452,21 +3577,21 @@ const surfaceCommands = [
 						queryName: "page",
 						description: "The page to return, starting at 1",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int()
 					},
 					{
 						name: "limit",
 						queryName: "limit",
 						description: "The number of records per page, from 1 to 100",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int().min(1).max(100)
 					},
 					{
 						name: "sort-by",
 						queryName: "sortBy",
 						description: "The field to sort by",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"name",
 							"sku",
 							"type",
@@ -3478,14 +3603,14 @@ const surfaceCommands = [
 						queryName: "sortOrder",
 						description: "The sort direction",
 						valueName: "value",
-						schema: z.enum(["ASC", "DESC"])
+						schema: toEnum(["ASC", "DESC"])
 					},
 					{
 						name: "archived",
 						queryName: "archived",
 						description: "Whether to return unarchived records, archived records, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -3546,7 +3671,7 @@ const surfaceCommands = [
 						description: "SERVICE for a non-physical item, DEVICE for a physical item tracked by serial number, or BULK for a part tracked by quantity",
 						valueName: "value",
 						required: true,
-						schema: z.enum([
+						schema: toEnum([
 							"BULK",
 							"DEVICE",
 							"SERVICE"
@@ -3557,7 +3682,7 @@ const surfaceCommands = [
 						jsonPath: ["unitOfMeasure"],
 						description: "The unit a BULK item's quantities are counted in, which SERVICE and DEVICE items ignore",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"BG",
 							"BO",
 							"BX",
@@ -3703,7 +3828,7 @@ const surfaceCommands = [
 						description: "The type to convert the item to, when the item's assets and inventory history allow the conversion",
 						valueName: "value",
 						nullable: true,
-						schema: z.enum([
+						schema: toEnum([
 							"BULK",
 							"DEVICE",
 							"SERVICE"
@@ -3751,7 +3876,7 @@ const surfaceCommands = [
 							jsonPath: ["depreciationModel"],
 							description: "The method one unit is depreciated by, or null to clear it",
 							valueName: "value",
-							schema: z.enum([
+							schema: toEnum([
 								"DOUBLE_DECLINING",
 								"STRAIGHT_LINE",
 								"SUM_YEAR",
@@ -3836,7 +3961,7 @@ const surfaceCommands = [
 							description: "The number of months one unit is depreciated over, or null to clear it",
 							valueName: "number",
 							nullable: true,
-							schema: z.coerce.number()
+							schema: z.coerce.number().int()
 						}
 					]
 				})]
@@ -3867,7 +3992,7 @@ const surfaceCommands = [
 								description: "The kind of value the field holds",
 								valueName: "value",
 								required: true,
-								schema: z.enum([
+								schema: toEnum([
 									"BOOLEAN",
 									"DATE",
 									"DATE_TIME",
@@ -3893,7 +4018,7 @@ const surfaceCommands = [
 								valueName: "number",
 								required: true,
 								nullable: true,
-								schema: z.coerce.number()
+								schema: z.coerce.number().int()
 							},
 							{
 								name: "section",
@@ -3902,7 +4027,7 @@ const surfaceCommands = [
 								valueName: "number",
 								required: true,
 								nullable: true,
-								schema: z.coerce.number()
+								schema: z.coerce.number().int()
 							}
 						]
 					}),
@@ -3973,21 +4098,21 @@ const surfaceCommands = [
 						queryName: "page",
 						description: "The page to return, starting at 1",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int()
 					},
 					{
 						name: "limit",
 						queryName: "limit",
 						description: "The number of records per page, from 1 to 100",
 						valueName: "number",
-						schema: z.coerce.number()
+						schema: z.coerce.number().int().min(1).max(100)
 					},
 					{
 						name: "sort-by",
 						queryName: "sortBy",
 						description: "The field to sort by",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"name",
 							"company",
 							"assetCount"
@@ -3998,14 +4123,14 @@ const surfaceCommands = [
 						queryName: "sortOrder",
 						description: "The sort direction",
 						valueName: "value",
-						schema: z.enum(["ASC", "DESC"])
+						schema: toEnum(["ASC", "DESC"])
 					},
 					{
 						name: "archived",
 						queryName: "archived",
 						description: "Whether to return unarchived records, archived records, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -4016,7 +4141,7 @@ const surfaceCommands = [
 						queryName: "isTransient",
 						description: "Whether to return permanent locations (false), transient locations (true), or both (all)",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -4181,7 +4306,7 @@ const surfaceCommands = [
 						jsonPath: ["type"],
 						description: "SITE for a site, or ZONE for a zone within a site",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"SITE",
 							"UNKNOWN",
 							"ZONE"
@@ -4337,7 +4462,7 @@ const surfaceCommands = [
 						jsonPath: ["type"],
 						description: "SITE for a site, or ZONE for a zone within a site",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"SITE",
 							"UNKNOWN",
 							"ZONE"
@@ -4367,7 +4492,7 @@ const surfaceCommands = [
 						queryName: "archived",
 						description: "Whether to return unarchived zones, archived zones, or all of them",
 						valueName: "value",
-						schema: z.enum([
+						schema: toEnum([
 							"all",
 							"false",
 							"true"
@@ -4378,6 +4503,23 @@ const surfaceCommands = [
 			}
 		]
 	},
+	{
+		name: "token",
+		summary: "Token commands",
+		arguments: [],
+		flags: [],
+		examples: [],
+		subcommands: [defineOperation({
+			name: "get",
+			summary: "Report the credential this CLI is calling with",
+			example: "hardfin token get",
+			method: "GET",
+			path: "/token",
+			pathParameters: [],
+			queryFlags: [],
+			bodyFlags: []
+		})]
+	},
 	{
 		name: "url-link",
 		summary: "URL link commands",
@@ -4445,32 +4587,6 @@ const surfaceCommands = [
 	}
 ];
 //#endregion
-//#region src/auth/jwt.ts
-/**
-* toClaims reads an access token's payload for display. Nothing here verifies the
-* signature, because the API is what decides whether a token is good.
-*/
-function toClaims(token) {
-	const payload = token.split(".")[1];
-	if (!payload) return {};
-	try {
-		const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
-		return {
-			expiresAt: typeof decoded["exp"] === "number" ? decoded["exp"] * 1e3 : void 0,
-			issuedAt: typeof decoded["iat"] === "number" ? decoded["iat"] * 1e3 : void 0,
-			scopes: toScopes(decoded),
-			subject: typeof decoded["sub"] === "string" ? decoded["sub"] : void 0
-		};
-	} catch {
-		return {};
-	}
-}
-/** toScopes reads scp, which is where Hardfin puts an access token's scopes. */
-function toScopes(decoded) {
-	if (Array.isArray(decoded["scp"])) return decoded["scp"].map(String);
-	return typeof decoded["scope"] === "string" ? decoded["scope"].split(" ") : void 0;
-}
-//#endregion
 //#region src/system/host.ts
 const BYTES_PER_GB = 1024 ** 3;
 /** toDistribution reads the name a Linux distribution gives itself. */
@@ -4514,8 +4630,8 @@ function toFile(path) {
 //#endregion
 //#region src/command/status.ts
 /**
-* Hardfin expires an unused refresh token after this long. It is the server's rule, not the
-* CLI's, and the token endpoint reports no expiry, so what this produces is an estimate.
+* What the CLI falls back to for an older sign in, stored before the server began reporting
+* when a refresh token expires. Hardfin's own rule, and an estimate rather than a fact.
 */
 const REFRESH_SLIDING_DAYS = 90;
 const statusCommand = defineCommand({
@@ -4619,8 +4735,8 @@ function toCredentialReport(apiKey, stored) {
 		fingerprint: toFingerprint(stored.refreshToken),
 		signedInAt: stored.signedInAt ?? null,
 		renewedAt: stored.renewedAt ?? null,
-		refreshExpiresAt: toRefreshExpiry(stored.renewedAt),
-		refreshExpiryIsEstimated: true
+		refreshExpiresAt: stored.expiresAt ?? toRefreshExpiry(stored.renewedAt),
+		refreshExpiryIsEstimated: stored.expiresAt === void 0
 	};
 }
 function toServerReport(metadata) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hardfin/cli",
-    "version": "0.0.2-dev.13",
+    "version": "0.0.2-dev.15",
     "description": "Command line interface for the Hardfin API",
     "license": "Apache-2.0",
     "author": "Hardfin, Inc.",
@@ -46,6 +46,7 @@
     },
     "devDependencies": {
         "@types/node": "^22.15.0",
+        "@vitest/coverage-v8": "^5.0.1",
         "tsdown": "^0.23.0",
         "typescript": "^5.9.0",
         "unrun": "^0.3.1",