@gjermundgaraba/clankercreds 0.2.0 → 0.4.0

package/dist/admin-DC0cTmmT.mjs

@@ -0,0 +1,342 @@
+import { a as LoginKind, c as NotFound, f as scopes, i as Host, l as SecretKind, m as ProviderUnavailable, n as Conflict, o as Name, p as CurrentPrincipal, s as NeedsSignIn, u as UpstreamUnavailable } from "./shared-C56uw1xx.mjs";
+import { Config, Console, Effect, Option, Redacted, Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http";
+import { execFile } from "node:child_process";
+import { text } from "node:stream/consumers";
+import { CliError, Command, Flag } from "effect/cli";
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+//#region ../../packages/api/src/admin.ts
+/** Written by the service, always ISO. What an operator enters is decoded as a date instead. */
+const Timestamp = Schema.String;
+/** A stored secret's state. The value itself is never read back out. */
+const SecretStatus = Schema.Struct({
+	name: Name,
+	kind: SecretKind,
+	/** The host a `gh` token is for; null for every other kind. */
+	host: Schema.NullOr(Schema.String),
+	expiresAt: Schema.NullOr(Timestamp),
+	createdAt: Timestamp,
+	updatedAt: Timestamp
+});
+/** A login's state. It exists from the first completed sign-in on. */
+const LoginStatus = Schema.Struct({
+	name: Name,
+	kind: LoginKind,
+	needsSignIn: Schema.Boolean,
+	email: Schema.NullOr(Schema.String),
+	/** The ChatGPT account a ChatGPT login is for; null for every other kind. */
+	accountId: Schema.NullOr(Schema.String),
+	accessExpiresAt: Timestamp,
+	lastRefreshAt: Timestamp,
+	lastError: Schema.NullOr(Schema.String),
+	createdAt: Timestamp,
+	updatedAt: Timestamp
+});
+const CredentialStatus = Schema.Union([SecretStatus, LoginStatus]);
+/** The clankerauth id of a machine key. */
+const KeyId = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
+/**
+* A machine key and the credentials it may read. A machine names which of them it syncs; a
+* replacement key is granted the same ones and overlaps the old key until that is removed.
+* A key may be granted several credentials of one kind: several accounts of a provider.
+*/
+const KeyInfo = Schema.Struct({
+	id: KeyId,
+	credentials: Schema.Array(Name)
+});
+/**
+* A pending Claude sign-in: approve at `authorizeUrl`, then hand the code the callback page
+* shows to `completeClaudeSignIn`. The code is useless without the verifier the service holds.
+*/
+const ClaudeSignIn = Schema.Struct({
+	signInId: Schema.String,
+	credential: Name,
+	authorizeUrl: Schema.String,
+	expiresAt: Timestamp
+});
+/**
+* A Claude sign-in's code was not taken: it is not this sign-in's, or Anthropic refused it.
+* The sign-in stays open until it expires, for the code again or a new one from its
+* `authorizeUrl`. An approval that left out a scope the token needs ends it: start again.
+*/
+var SignInRefused = class extends Schema.TaggedError()("SignInRefused", { message: Schema.String }, { httpApiStatus: 422 }) {};
+/**
+* A login's sign-in: open `verificationUrl` and approve, entering `userCode` where the
+* provider asks for one. Cursor's link carries everything and has no code.
+*/
+const SignInState = Schema.Struct({
+	signInId: Schema.String,
+	credential: Name,
+	kind: LoginKind,
+	status: Schema.Literals([
+		"pending",
+		"complete",
+		"failed",
+		"expired"
+	]),
+	userCode: Schema.NullOr(Schema.String),
+	verificationUrl: Schema.String,
+	expiresAt: Timestamp,
+	message: Schema.optionalKey(Schema.String)
+});
+/** Credentials by name: rows outlive what they name, and stay findable. */
+const AuditEntry = Schema.Struct({
+	id: Schema.Int,
+	at: Timestamp,
+	actorKind: Schema.Literals([
+		"machine",
+		"admin",
+		"system"
+	]),
+	keyId: Schema.NullOr(Schema.String),
+	clientId: Schema.NullOr(Schema.String),
+	action: Schema.String,
+	credential: Schema.NullOr(Schema.String),
+	remoteAddr: Schema.NullOr(Schema.String),
+	detail: Schema.Record(Schema.String, Schema.Json)
+});
+/** Every filter is optional; the page size defaults on the service. */
+const AuditQuery = Schema.Struct({
+	limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({
+		minimum: 1,
+		maximum: 500
+	}))),
+	before: Schema.optionalKey(Schema.Int),
+	action: Schema.optionalKey(Schema.String),
+	credential: Schema.optionalKey(Name),
+	keyId: Schema.optionalKey(Schema.String),
+	clientId: Schema.optionalKey(Schema.String)
+});
+/**
+* A read whose code or link signs an account in: exported so the server's authorization
+* rule can name it.
+*/
+const GetSignIn = Action.make("getSignIn", {
+	readOnly: true,
+	caller: CurrentPrincipal,
+	description: "Read a sign-in. The service holds one in memory only, until the next sign-in starts after it expired; one it no longer holds is not found.",
+	input: Schema.Struct({ signInId: Schema.String }),
+	success: SignInState,
+	error: NotFound
+});
+/** Everything an operator does; which scope each needs is the server's authorization rule. */
+const Admin = [
+	Action.make("listCredentials", {
+		readOnly: true,
+		caller: CurrentPrincipal,
+		description: "Every credential with its state: expiry, last refresh, last error and whether a login needs a new sign-in. Values are never returned.",
+		success: Schema.Struct({ credentials: Schema.Array(CredentialStatus) })
+	}),
+	Action.make("putCredential", {
+		readOnly: false,
+		caller: CurrentPrincipal,
+		description: "Store a secret under a name, or replace its value and expiry: a `gh` or `claude` token a machine places, or a `token`, any other service's API key, which a service such as clankerusage reads. A `gh` token is for `host`, github.com unless given. A credential's kind and host never change; remove it and put it again instead. Keys granted it receive it on their next sync.",
+		input: Schema.Struct({
+			name: Name,
+			kind: SecretKind,
+			value: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(16384)),
+			host: Schema.optionalKey(Host),
+			/** Any date string JavaScript parses; a typo is refused, so alerting never loses it. Left out, it does not expire. */
+			expiresAt: Schema.optionalKey(Schema.DateFromString)
+		}).check(Schema.makeFilter(({ kind, host }) => kind === "gh" || host === void 0 ? void 0 : {
+			path: ["host"],
+			issue: "Only a gh credential has a host."
+		})),
+		success: SecretStatus,
+		error: Conflict
+	}),
+	Action.make("removeCredential", {
+		readOnly: false,
+		caller: CurrentPrincipal,
+		description: "Delete a credential. Refused while a key is still granted it.",
+		input: Schema.Struct({ name: Name }),
+		success: Schema.Void,
+		error: [NotFound, Conflict]
+	}),
+	Action.make("startSignIn", {
+		readOnly: false,
+		caller: CurrentPrincipal,
+		description: "Start a sign-in for a ChatGPT, Grok or Cursor login; the credential is created, or its login replaced, when the sign-in completes. Open the returned verificationUrl and approve, entering userCode where one is given, then poll getSignIn.",
+		input: Schema.Struct({
+			name: Name,
+			kind: LoginKind
+		}),
+		success: SignInState,
+		error: [Conflict, UpstreamUnavailable]
+	}),
+	GetSignIn,
+	Action.make("refreshCredential", {
+		readOnly: false,
+		caller: CurrentPrincipal,
+		description: "Refresh one login now instead of waiting for its schedule.",
+		input: Schema.Struct({ name: Name }),
+		success: LoginStatus,
+		error: [
+			NotFound,
+			Conflict,
+			NeedsSignIn,
+			UpstreamUnavailable
+		]
+	}),
+	Action.make("startClaudeSignIn", {
+		readOnly: false,
+		caller: CurrentPrincipal,
+		description: "Start a sign-in for a Claude credential: a token for both Claude Code and the usage endpoint, valid for a year. Approve at the returned authorizeUrl, then pass the code the callback page shows to completeClaudeSignIn within 15 minutes.",
+		input: Schema.Struct({ name: Name }),
+		success: ClaudeSignIn,
+		error: Conflict
+	}),
+	Action.make("completeClaudeSignIn", {
+		readOnly: false,
+		caller: CurrentPrincipal,
+		description: "Exchange the code from an approved Claude sign-in for its token, stored under the sign-in's name: created, or its value and expiry replaced. Machines receive it on their next sync.",
+		input: Schema.Struct({
+			signInId: Schema.String,
+			/** As the callback page shows it: `<code>#<state>`. */
+			code: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(4096))
+		}),
+		success: SecretStatus,
+		error: [
+			NotFound,
+			Conflict,
+			SignInRefused,
+			UpstreamUnavailable
+		]
+	}),
+	Action.make("listKeys", {
+		readOnly: true,
+		caller: CurrentPrincipal,
+		description: "Every machine key with the credentials it is granted.",
+		success: Schema.Struct({ keys: Schema.Array(KeyInfo) })
+	}),
+	Action.make("putKey", {
+		readOnly: false,
+		caller: CurrentPrincipal,
+		description: "Grant a machine key, by its clankerauth id, exactly these credentials, replacing what it had; none takes every grant. A machine syncs the ones its configuration names; several of one kind may be granted. Revoke the key itself in clankerauth.",
+		input: Schema.Struct({
+			id: KeyId,
+			credentials: Schema.Array(Name)
+		}),
+		success: KeyInfo,
+		error: NotFound
+	}),
+	Action.make("listAudit", {
+		readOnly: true,
+		caller: CurrentPrincipal,
+		description: "The audit log, newest first. Filter by action, credential, key or client id; page with `before`.",
+		input: AuditQuery,
+		success: Schema.Struct({ entries: Schema.Array(AuditEntry) })
+	})
+];
+/**
+* An operator's bearer token on the private port: an access token or API key of the admin
+* resource, verified by its own provider.
+*/
+const AdminLogin = Authentication.make("clankercreds.admin", CurrentPrincipal, { error: ProviderUnavailable });
+const AdminHttp = ActionHttp.make(Admin, {
+	prefix: "/v1",
+	authentication: AdminLogin
+});
+//#endregion
+//#region package.json
+var version = "0.4.0";
+//#endregion
+//#region src/admin.ts
+/** A refusal of this command's own, printed as its message on stderr, exiting 1. */
+const refused = (message) => new CliError.UserError({
+	cause: message,
+	userMessage: message
+});
+/** What an operator signs in to clankerauth for: every admin action. */
+const operatorScopes = `${scopes.read} ${scopes.admin}`;
+/**
+* The admin port, and the resource its tokens are for: the port's origin root, unless the
+* service names its resource otherwise.
+*/
+const admin = Command.make("admin").pipe(Command.withSharedFlags({
+	url: Flag.String("url").pipe(Flag.withDescription("The admin port's origin; CLANKERCREDS_ADMIN_URL when left out"), Flag.withFallbackConfig(Config.String("CLANKERCREDS_ADMIN_URL"))),
+	resource: Flag.String("resource").pipe(Flag.withDescription("The service's clankerauth resource, as CLANKERCREDS_RESOURCE names it on the server; the admin origin's root when left out"), Flag.withFallbackConfig(Config.String("CLANKERCREDS_RESOURCE")), Flag.optional)
+}), Command.withDescription(`Administer clankercreds over its admin port. A command signs in with \`clankerauth token\`, so sign in once with \`clankerauth login <issuer> --resource <resource> --scope "${operatorScopes}"\`; CLANKERCREDS_ADMIN_TOKEN, an API key or access token, is used instead when set. Results are JSON on stdout.`));
+/** Run `clankerauth token` for `resource`: the CLI that holds the operator's sign-in. */
+const clankerauthToken = (resource) => Effect.callback((resume) => {
+	execFile("clankerauth", [
+		"token",
+		"--resource",
+		resource
+	], (error, stdout, stderr) => {
+		if (error === null) {
+			resume(Effect.succeed(stdout.trim()));
+			return;
+		}
+		resume(Effect.fail(refused("code" in error && error.code === "ENOENT" ? `clankerauth is not installed. Install it with \`npm install --global @gjermundgaraba/clankerauth\` and sign in with \`clankerauth login <issuer> --resource ${resource} --scope "${operatorScopes}"\`, or set CLANKERCREDS_ADMIN_TOKEN.` : `clankerauth token: ${stderr.trim() || error.message}`)));
+	});
+});
+/**
+* The client every admin command calls through: the admin origin and a bearer token,
+* CLANKERCREDS_ADMIN_TOKEN or a current one from `clankerauth token`.
+*/
+const operator = Effect.gen(function* () {
+	const { url, resource } = yield* admin;
+	const origin = yield* Effect.try({
+		try: () => new URL(url).origin,
+		catch: () => refused(`The admin URL must be a URL, such as https://clankercreds.example: ${url}`)
+	});
+	const given = yield* Config.option(Config.Redacted("CLANKERCREDS_ADMIN_TOKEN")).pipe(Effect.mapError(() => refused("CLANKERCREDS_ADMIN_TOKEN cannot be read")));
+	const token = yield* Option.match(given, {
+		onSome: (secret) => Effect.succeed(Redacted.value(secret)),
+		onNone: () => clankerauthToken(Option.getOrElse(resource, () => `${origin}/`))
+	});
+	return HttpClient.mapRequest(yield* HttpClient.HttpClient, (request) => request.pipe(HttpClientRequest.prependUrl(origin), HttpClientRequest.bearerToken(token)));
+});
+/**
+* The secret's value, from stdin: a flag would leave it in the process list and the shell's
+* history. Line endings a pipe adds, such as `op read`'s, are not part of it.
+*/
+const valueFromStdin = Effect.gen(function* () {
+	if (process.stdin.isTTY) return yield* refused("Pipe the value in, such as `op read 'op://…' | clankercreds admin put-credential …`; it is never taken from a flag or the terminal.");
+	const value = (yield* Effect.promise(() => text(process.stdin))).replace(/[\r\n]+$/, "");
+	if (value === "") return yield* refused("The value on stdin is empty.");
+	return value;
+});
+const json = (value) => Console.log(JSON.stringify(value, null, 2));
+/** `putCredential`, its value read from stdin and every other field a flag. */
+const putCredential = Command.make("put-credential", {
+	name: Flag.String("name").pipe(Flag.withDescription("The credential's name")),
+	kind: Flag.Literals("kind", SecretKind.literals).pipe(Flag.withDescription("What the secret is: a gh or claude token a machine places, or a token, any other service's API key")),
+	host: Flag.String("host").pipe(Flag.withDescription("A gh token's host; github.com when left out"), Flag.optional),
+	expiresAt: Flag.String("expires-at").pipe(Flag.withDescription("When the secret expires, any date string; it never does when left out"), Flag.optional)
+}, ({ name, kind, host, expiresAt }) => Effect.gen(function* () {
+	const value = yield* valueFromStdin;
+	const expiry = yield* Option.match(expiresAt, {
+		onNone: () => Effect.succeedNone,
+		onSome: (given) => {
+			const date = new Date(given);
+			return Number.isNaN(date.getTime()) ? Effect.fail(refused(`--expires-at is not a date: ${given}`)) : Effect.succeedSome(date);
+		}
+	});
+	const status = yield* (yield* ActionHttp.client(AdminHttp)).putCredential({
+		name,
+		kind,
+		value,
+		...Option.match(host, {
+			onNone: () => ({}),
+			onSome: (named) => ({ host: named })
+		}),
+		...Option.match(expiry, {
+			onNone: () => ({}),
+			onSome: (date) => ({ expiresAt: date })
+		})
+	}).pipe(Effect.mapError((error) => refused(`${error._tag}: ${error.message}`)));
+	yield* json(status);
+})).pipe(Command.withDescription("Store a secret under a name, or replace its value and expiry. The value is read from stdin."), Command.provideEffect(HttpClient.HttpClient, operator));
+/** Every other admin action, as a command derived from its contract. */
+const derived = Admin.filter((action) => action.name !== "putCredential").map((action) => ActionCli.remoteCommand(AdminHttp, action).pipe(Command.provideEffect(HttpClient.HttpClient, operator)));
+const cli = Command.make("clankercreds").pipe(Command.withSubcommands([admin.pipe(Command.withSubcommands([putCredential, ...derived]))]));
+/** Run `clankercreds admin …`; `args` are the process's, after the script. */
+const run = (args) => Command.runWith(cli, { version })(args).pipe(Effect.provide(FetchHttpClient.layer), Effect.provide(NodeServices.layer), ActionCli.logToStderr, NodeRuntime.runMain);
+//#endregion
+export { run };

package/dist/main.mjs

@@ -1,159 +1,40 @@
 #!/usr/bin/env node
+import { c as NotFound, d as claimsOf, m as ProviderUnavailable, o as Name, p as CurrentPrincipal, r as CredentialKind, s as NeedsSignIn, t as ClientId, u as UpstreamUnavailable } from "./shared-C56uw1xx.mjs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
-import { randomBytes } from "node:crypto";
-import { Context, Data, Effect, Option, Predicate, Schema } from "effect";
-import { HttpClient, HttpClientRequest } from "effect/http";
+import { Effect, Option, Predicate, Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { HttpClient, HttpClientRequest } from "effect/http";
 import { YAMLMap, isMap, parseDocument } from "yaml";
-//#region src/files.ts
-/** Secrets are readable by their owner only, in directories only the owner can enter. */
-const fileMode = 384;
-const directoryMode = 448;
-const isMissing = (error) => Predicate.hasProperty(error, "code") && error.code === "ENOENT";
-/** A missing file is `undefined`. A file that exists but cannot be read is not ours to replace. */
-const readText = (path) => {
-	try {
-		return readFileSync(path, "utf8");
-	} catch (error) {
-		if (isMissing(error)) return void 0;
-		throw error;
-	}
-};
+//#region ../../packages/api/src/credentials.ts
 /**
-* Write-then-rename, so a tool reading the file sees the old content or the new and never
-* half of one. The directory is created private; an existing one keeps its mode.
+* The credential an entry was delivered from, as it was asked for by name, and when what it
+* carries expires, as ISO: a secret's as the operator entered it, a login's access token's
+* own. Null never expires. A login delivered past it could not be renewed in time, as when its
+* provider is away: sync again later. Whether it needs a new sign-in is the operator's to see.
 */
-const writeAtomic = (path, content) => {
-	mkdirSync(dirname(path), {
-		recursive: true,
-		mode: directoryMode
-	});
-	const partial = `${path}.${randomBytes(6).toString("hex")}.tmp`;
-	try {
-		writeFileSync(partial, content, { mode: fileMode });
-		chmodSync(partial, fileMode);
-		renameSync(partial, path);
-	} catch (error) {
-		rmSync(partial, { force: true });
-		throw error;
-	}
-};
-/** True when there was a file to remove. */
-const remove = (path) => {
-	try {
-		unlinkSync(path);
-		return true;
-	} catch (error) {
-		if (isMissing(error)) return false;
-		throw error;
-	}
-};
-const isJsonObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/** The file as an object; a missing file is empty. Anything else is not ours to overwrite. */
-const readJsonObject = (path) => {
-	const text = readText(path);
-	if (text === void 0 || text.trim() === "") return {};
-	const parsed = JSON.parse(text);
-	if (!isJsonObject(parsed)) throw new Error(`${path} does not hold a JSON object`);
-	return parsed;
+const fromCredential = {
+	credential: Name,
+	expiresAt: Schema.NullOr(Schema.String)
 };
-/**
-* A nested object a placement merges into; a missing one is empty. Anything else under the
-* key is someone else's, however malformed, and not ours to overwrite.
-*/
-const objectAt = (parent, key, path) => {
-	const value = parent[key];
-	if (value === void 0) return {};
-	if (!isJsonObject(value)) throw new Error(`${key} in ${path} is not a JSON object; refusing to replace it`);
-	return value;
-};
-const writeJson = (path, value) => writeAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
-//#endregion
-//#region src/config.ts
-/** Where the recipe puts `config.json` and `key`. The variable exists for tests and odd images. */
-const configDirectory = () => process.env["CLANKERCREDS_CONFIG_DIR"] ?? "/etc/clankercreds";
-/** The environment is read here and nowhere else, so a placement goes only where it is told. */
-const configHome = (home) => {
-	const xdg = process.env["XDG_CONFIG_HOME"];
-	return xdg === void 0 || xdg === "" ? join(home, ".config") : xdg;
-};
-/** The bundle is not named here: the key is bound to it on the service. */
-const loadConfig = () => {
-	const directory = configDirectory();
-	const file = join(directory, "config.json");
-	const { service } = readJsonObject(file);
-	if (typeof service !== "string") throw new Error(`${file} must hold {"service": "https://…"}`);
-	const key = readText(join(directory, "key"))?.trim();
-	if (key === void 0 || key === "") throw new Error(`${join(directory, "key")} must hold the machine key`);
-	const home = homedir();
-	return {
-		service: service.replace(/\/+$/, ""),
-		key,
-		home,
-		configHome: configHome(home)
-	};
-};
-Data.TaggedError("Unauthorized");
-/**
-* The issuer could not be reached, so the credential could not be decided: a 503, not a
-* refusal. A resource's descriptor declares it,
-* `Authentication.make("notes.Login", CurrentPrincipal, { error: ProviderUnavailable })`.
-* Its public response is the schema. Diagnostic causes are internal, non-enumerable fields.
-*/
-var ProviderUnavailable = class extends Schema.TaggedError()("ProviderUnavailable", { operation: Schema.String }, { httpApiStatus: 503 }) {
-	constructor(options) {
-		super({ operation: options.operation });
-		Object.defineProperty(this, "cause", { value: options.cause });
-	}
-};
-Data.TaggedError("InsufficientScope");
-Schema.TaggedError()("ConfigurationError", { message: Schema.String });
-//#endregion
-//#region ../../node_modules/.pnpm/@gjermundgaraba+clankerauth-sdk@0.13.0_@gjermundgaraba+effect-actions@0.10.0_effect@4.0.0__effect@4.0.0/node_modules/@gjermundgaraba/clankerauth-sdk/dist/session.js
-/**
-* The identity a browser page needs, without any verification code. This entry point is
-* browser-safe: it declares the identity a protected contract states, the `whoami` contract
-* and the issuer's sign-out URL, so contracts, bindings and pages import it directly, and a
-* server answers `Whoami` with its resource's `session`.
-*/
-/**
-* The caller: what a protected contract states, `caller: CurrentPrincipal`, and what an
-* authentication descriptor proves,
-* `Authentication.make("notes.Login", CurrentPrincipal, { error: ProviderUnavailable })`.
-* Remotely, the resource's provider gives it per request, from the verified credential; on
-* a trusted local surface, the host gives it the process, `Notes.local(subject)`.
-*/
-var CurrentPrincipal = class extends Context.Service()("@clankerauth/CurrentPrincipal") {};
-/** The verified credential behind a request, as the resource server read it. */
-const Principal = Schema.Struct({
-	subject: Schema.NonEmptyString,
-	issuer: Schema.NonEmptyString,
-	scopes: Schema.Array(Schema.String)
-});
-Action.make("whoami", {
-	description: "The verified subject, issuer and scopes behind this request's credential.",
-	readOnly: true,
-	caller: CurrentPrincipal,
-	success: Principal
-});
-//#endregion
-//#region ../../packages/api/src/bundle.ts
 const GhCredential = Schema.Struct({
 	type: Schema.Literal("gh"),
+	...fromCredential,
 	host: Schema.String,
 	token: Schema.String
 });
 const ClaudeCredential = Schema.Struct({
 	type: Schema.Literal("claude"),
+	...fromCredential,
 	token: Schema.String
 });
 /**
 * What Codex keeps in its `auth.json`, always written together: the three belong to one
-* login. No refresh token: the client writes `<clientId>:<key>` in its place.
+* login. No refresh token: the client writes `<clientId>:<credential>:<key>` in its place.
 */
 const CodexLogin = Schema.Struct({
 	accessToken: Schema.String,
@@ -162,6 +43,7 @@ const CodexLogin = Schema.Struct({
 });
 const CodexCredential = Schema.Struct({
 	type: Schema.Literal("codex"),
+	...fromCredential,
 	...CodexLogin.fields
 });
 /**
@@ -170,24 +52,38 @@ const CodexCredential = Schema.Struct({
 */
 const PiCredential = Schema.Struct({
 	type: Schema.Literal("pi"),
+	...fromCredential,
 	accessToken: Schema.String
 });
 /**
+* A credential no machine places: an API key, or a Grok or Cursor login's access token, for
+* a service such as clankerusage that knows which provider each name is for. A machine
+* whose config names one refuses the sync.
+*/
+const TokenCredential = Schema.Struct({
+	type: Schema.Literal("token"),
+	...fromCredential,
+	token: Schema.String
+});
+/**
 * The service sends typed credentials, never file contents or paths, so it cannot write
 * anything on a machine but what the client knows how to place. The cost is that a new
-* tool, or a placement fix, needs a client release, which new machines install.
+* tool, or a placement fix, needs a client release, which new machines install. Each entry
+* names the credential it came from: a ChatGPT login arrives as a `codex` and a `pi` entry
+* under the same name.
 *
 * Each machine keeps the client its setup installed, so old clients read what the service sends. A change
 * an old client would get wrong is a new type name, which it skips: the decoder drops fields
 * it does not know, so one ignoring `host` would place a GHE token as github.com's. A field
-* an old client can safely ignore may be added, as pi's `accessToken` was; the service ships
-* first, since a new client refuses a bundle that lacks it.
+* an old client can safely ignore may be added; the service ships first, since a new client
+* refuses an entry that lacks it.
 */
 const TypedCredential = Schema.Union([
 	GhCredential,
 	ClaudeCredential,
 	CodexCredential,
-	PiCredential
+	PiCredential,
+	TokenCredential
 ]);
 /** The types this build knows, derived from the union so there is one list. */
 const knownTypes = TypedCredential.members.map((member) => member.fields.type.literal);
@@ -198,77 +94,54 @@ const isKnownType = (type) => knownTypes.some((known) => known === type);
 * schema must not land here, or a broken credential would be placed as an empty one.
 */
 const UnknownCredential = Schema.Struct({ type: Schema.String.check(Schema.makeFilter((type) => !isKnownType(type), { message: "a known credential type must match its schema" })) });
-/** Everything the machine's bundle holds, sent in full on every sync. */
-const Bundle = Schema.Struct({ credentials: Schema.Array(Schema.Union([TypedCredential, UnknownCredential])) });
+/** Everything the caller asked for, sent in full on every sync. */
+const Delivery = Schema.Struct({ credentials: Schema.Array(Schema.Union([TypedCredential, UnknownCredential])) });
 //#endregion
-//#region ../../packages/api/src/shared.ts
-/**
-* What was asked for does not exist: a bundle, credential or sign-in by that name, a
-* bundle for the calling key, or a ChatGPT login in the bundle that has none.
-*/
-var NotFound = class extends Schema.TaggedError()("NotFound", { message: Schema.String }, { httpApiStatus: 404 }) {};
-Schema.TaggedError()("Conflict", { message: Schema.String }, { httpApiStatus: 409 });
-/** The ChatGPT login is dead, or was never completed. Only a new device sign-in revives it. */
-var NeedsSignIn = class extends Schema.TaggedError()("NeedsSignIn", { message: Schema.String }, { httpApiStatus: 409 }) {};
-/** OpenAI could not be reached and no valid token is held. Waiting helps; retrying now does not. */
-var UpstreamUnavailable = class extends Schema.TaggedError()("UpstreamUnavailable", { message: Schema.String }, { httpApiStatus: 503 }) {};
-Schema.String.check(Schema.isPattern(/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/));
-Schema.String.check(Schema.isPattern(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/), Schema.isMaxLength(253));
-/**
-* The machine's self-generated label. It identifies nothing; it only groups audit rows.
-* It excludes `:` because the Codex refresh token is `<clientId>:<key>`.
-*/
-const ClientId = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_-]{1,64}$/));
-const Claims = Schema.Struct({
-	exp: Schema.optionalKey(Schema.Number),
-	email: Schema.optionalKey(Schema.String),
-	"https://api.openai.com/auth": Schema.optionalKey(Schema.Struct({ chatgpt_account_id: Schema.optionalKey(Schema.String) }))
+//#region ../../packages/api/src/machine.ts
+/** A credential the calling key may read, without its value. */
+const Grant = Schema.Struct({
+	name: Name,
+	kind: CredentialKind
 });
 /**
-* The claims of an OpenAI JWT, unverified: they are read for their timing and their
-* account, never trusted for anything. Anything unreadable is simply no claims.
+* What a machine key can do: read the credentials it is granted, by name, and nothing else.
+* The caller names what it wants; the grants on the server decide whether it may. A machine
+* is one caller; a service such as clankerusage, holding a key of its own, is another.
 */
-const claimsOf = (jwt) => {
-	const payload = Buffer.from(jwt.split(".")[1] ?? "", "base64url").toString("utf8");
-	const claims = Schema.decodeUnknownOption(Schema.fromJsonString(Claims))(payload);
-	return Option.match(claims, {
-		onNone: () => ({
-			exp: void 0,
-			email: void 0,
-			accountId: void 0
+const Machine = [
+	Action.make("sync", {
+		readOnly: false,
+		caller: CurrentPrincipal,
+		description: "Fetch the named credentials as typed entries, each with its expiry; a login near expiry is refreshed first. Refused whole when the calling key is not granted any one of them.",
+		input: Schema.Struct({
+			clientId: ClientId,
+			credentials: Schema.Array(Name)
 		}),
-		onSome: (value) => ({
-			exp: value.exp,
-			email: value.email,
-			accountId: value["https://api.openai.com/auth"]?.chatgpt_account_id
-		})
-	});
-};
-//#endregion
-//#region ../../packages/api/src/machine.ts
-/**
-* What a machine key can do: read the one bundle bound to it, and nothing else. The
-* bundle is never named: the key is bound to it on the server.
-*/
-const Machine = [Action.make("bundle", {
-	readOnly: false,
-	caller: CurrentPrincipal,
-	description: "Fetch the typed credentials of the bundle bound to the calling key.",
-	input: Schema.Struct({ clientId: ClientId }),
-	success: Bundle,
-	error: NotFound
-}), Action.make("codexLogin", {
-	readOnly: false,
-	caller: CurrentPrincipal,
-	description: "The current ChatGPT login of the bundle bound to the calling key, as the codex type carries it, refreshed first when it has expired.",
-	input: Schema.Struct({ clientId: ClientId }),
-	success: CodexLogin,
-	error: [
-		NotFound,
-		NeedsSignIn,
-		UpstreamUnavailable
-	]
-})];
+		success: Delivery,
+		error: NotFound
+	}),
+	Action.make("codexLogin", {
+		readOnly: false,
+		caller: CurrentPrincipal,
+		description: "The current login of a ChatGPT credential the calling key is granted, as the codex type carries it, refreshed first when it has expired.",
+		input: Schema.Struct({
+			clientId: ClientId,
+			credential: Name
+		}),
+		success: CodexLogin,
+		error: [
+			NotFound,
+			NeedsSignIn,
+			UpstreamUnavailable
+		]
+	}),
+	Action.make("listGrants", {
+		readOnly: true,
+		caller: CurrentPrincipal,
+		description: "The names and kinds of the credentials the calling key is granted, so a caller can offer them to pick from. Values are never returned.",
+		success: Schema.Struct({ credentials: Schema.Array(Grant) })
+	})
+];
 /**
 * Codex treats a 401 as permanent and stops retrying; every other failure is transient.
 * The codes are the ones Codex classifies: `refresh_token_invalidated` reads as revoked.
@@ -283,7 +156,7 @@ var CodexRefreshUnavailable = class extends Schema.TaggedError()("CodexRefreshUn
 }) }, { httpApiStatus: 503 }) {};
 /**
 * Codex's own refresh request, the one request whose shape is not ours. The refresh-token
-* field carries `<clientId>:<key>`, so the contract is public and its handler authenticates
+* field carries `<clientId>:<credential>:<key>`, so the contract is public and its handler authenticates
 * the key against the machine resource. The answer leaves `refresh_token` out, so Codex keeps the
 * composite it has. Its input alone accepts fields it does not name: Codex may add one,
 * and every other action refuses them.
@@ -291,7 +164,7 @@ var CodexRefreshUnavailable = class extends Schema.TaggedError()("CodexRefreshUn
 const CodexRefresh = Action.make("codexRefresh", {
 	readOnly: false,
 	caller: Action.Anyone,
-	description: "Answer Codex's token refresh with the bundle's current ChatGPT tokens.",
+	description: "Answer Codex's token refresh with the current tokens of the ChatGPT credential its composite names.",
 	input: Schema.StructWithRest(Schema.Struct({
 		grant_type: Schema.Literal("refresh_token"),
 		refresh_token: Schema.String,
@@ -304,14 +177,21 @@ const CodexRefresh = Action.make("codexRefresh", {
 	}),
 	error: [CodexRefreshRejected, CodexRefreshUnavailable]
 });
-/** `<clientId>:<key>`. Client ids exclude `:`, so the key is the rest. */
-const formatCodexRefreshToken = (clientId, key) => `${clientId}:${key}`;
+/**
+* `<clientId>:<credential>:<key>`: a key may be granted several ChatGPT logins, so the
+* composite names the one Codex holds. Client ids and names exclude `:`, so the key is the rest.
+*/
+const formatCodexRefreshToken = (clientId, credential, key) => `${clientId}:${credential}:${key}`;
 const parseCodexRefreshToken = (value) => {
-	const colon = value.indexOf(":");
-	return colon < 1 || colon === value.length - 1 ? void 0 : {
-		clientId: value.slice(0, colon),
-		key: value.slice(colon + 1)
-	};
+	const first = value.indexOf(":");
+	const second = value.indexOf(":", first + 1);
+	if (first < 1 || second === -1 || second === value.length - 1) return void 0;
+	const credential = value.slice(first + 1, second);
+	return Schema.is(Name)(credential) ? {
+		clientId: value.slice(0, first),
+		credential,
+		key: value.slice(second + 1)
+	} : void 0;
 };
 /**
 * A machine key's bearer token on the public port, verified by the machine resource's own
@@ -324,6 +204,99 @@ const MachineHttp = ActionHttp.make([...Machine, CodexRefresh], {
 	authentication: MachineLogin
 });
 //#endregion
+//#region src/files.ts
+/** Secrets are readable by their owner only, in directories only the owner can enter. */
+const fileMode = 384;
+const directoryMode = 448;
+const isMissing = (error) => Predicate.hasProperty(error, "code") && error.code === "ENOENT";
+/** A missing file is `undefined`. A file that exists but cannot be read is not ours to replace. */
+const readText = (path) => {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		if (isMissing(error)) return void 0;
+		throw error;
+	}
+};
+/**
+* Write-then-rename, so a tool reading the file sees the old content or the new and never
+* half of one. The directory is created private; an existing one keeps its mode.
+*/
+const writeAtomic = (path, content) => {
+	mkdirSync(dirname(path), {
+		recursive: true,
+		mode: directoryMode
+	});
+	const partial = `${path}.${randomBytes(6).toString("hex")}.tmp`;
+	try {
+		writeFileSync(partial, content, { mode: fileMode });
+		chmodSync(partial, fileMode);
+		renameSync(partial, path);
+	} catch (error) {
+		rmSync(partial, { force: true });
+		throw error;
+	}
+};
+/** True when there was a file to remove. */
+const remove = (path) => {
+	try {
+		unlinkSync(path);
+		return true;
+	} catch (error) {
+		if (isMissing(error)) return false;
+		throw error;
+	}
+};
+const isJsonObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The file as an object; a missing file is empty. Anything else is not ours to overwrite. */
+const readJsonObject = (path) => {
+	const text = readText(path);
+	if (text === void 0 || text.trim() === "") return {};
+	const parsed = JSON.parse(text);
+	if (!isJsonObject(parsed)) throw new Error(`${path} does not hold a JSON object`);
+	return parsed;
+};
+/**
+* A nested object a placement merges into; a missing one is empty. Anything else under the
+* key is someone else's, however malformed, and not ours to overwrite.
+*/
+const objectAt = (parent, key, path) => {
+	const value = parent[key];
+	if (value === void 0) return {};
+	if (!isJsonObject(value)) throw new Error(`${key} in ${path} is not a JSON object; refusing to replace it`);
+	return value;
+};
+const writeJson = (path, value) => writeAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
+//#endregion
+//#region src/config.ts
+/** Where the recipe puts `config.json` and `key`. The variable exists for tests and odd images. */
+const configDirectory = () => process.env["CLANKERCREDS_CONFIG_DIR"] ?? "/etc/clankercreds";
+/** The environment is read here and nowhere else, so a placement goes only where it is told. */
+const configHome = (home) => {
+	const xdg = process.env["XDG_CONFIG_HOME"];
+	return xdg === void 0 || xdg === "" ? join(home, ".config") : xdg;
+};
+const ConfigFile = Schema.Struct({
+	service: Schema.String,
+	credentials: Schema.Array(Name)
+});
+/** The machine names what it syncs; the service decides whether its key may read it. */
+const loadConfig = () => {
+	const directory = configDirectory();
+	const file = join(directory, "config.json");
+	const { service, credentials } = Option.getOrThrowWith(Schema.decodeUnknownOption(ConfigFile)(readJsonObject(file)), () => /* @__PURE__ */ new Error(`${file} must hold {"service": "https://…", "credentials": ["github-main", …]}, each name in lowercase letters, digits and dashes`));
+	const key = readText(join(directory, "key"))?.trim();
+	if (key === void 0 || key === "") throw new Error(`${join(directory, "key")} must hold the machine key`);
+	const home = homedir();
+	return {
+		service: service.replace(/\/+$/, ""),
+		credentials,
+		key,
+		home,
+		configHome: configHome(home)
+	};
+};
+//#endregion
 //#region src/service.ts
 /** The service answered and said no. Retrying the same request will not help. */
 var Refused = class extends Error {};
@@ -350,8 +323,15 @@ const classify = (error) => {
 * the command about ten seconds, and a hang would cost it a token it already holds.
 */
 const within = (call, deadlineMs) => Effect.runPromise(Effect.timeout(call, deadlineMs)).catch((error) => Promise.reject(classify(error)));
-const fetchBundle = (config, clientId, deadlineMs = 3e4) => within(connect(config).bundle({ clientId }), deadlineMs);
-const fetchCodexLogin = (config, clientId, deadlineMs = 5e3) => within(connect(config).codexLogin({ clientId }), deadlineMs);
+/** The credentials the config names, refused whole when the key is not granted any one. */
+const fetchDelivery = (config, clientId, deadlineMs = 3e4) => within(connect(config).sync({
+	clientId,
+	credentials: config.credentials
+}), deadlineMs);
+const fetchCodexLogin = (config, clientId, credential, deadlineMs = 5e3) => within(connect(config).codexLogin({
+	clientId,
+	credential
+}), deadlineMs);
 //#endregion
 //#region src/place/claude.ts
 const settingsFile = (home) => join(home, ".claude/settings.json");
@@ -393,8 +373,8 @@ const removeClaude = (home) => {
 const authFile$1 = (home) => join(home, ".codex/auth.json");
 /**
 * The file's tokens, when its refresh-token field is a composite: then clankercreds wrote
-* it, for whichever identity the composite names. A login anyone else wrote has a real
-* refresh token there.
+* it, for whichever identity and credential the composite names. A login anyone else wrote
+* has a real refresh token there.
 */
 const ownTokens = (auth) => {
 	const tokens = auth["tokens"];
@@ -410,19 +390,20 @@ const ownTokens = (auth) => {
 /**
 * The one writer of the file, and it always writes the whole login: the three tokens
 * belong together. The refresh-token field never holds OpenAI's token: it names this
-* machine to the service, which Codex calls when `CODEX_REFRESH_TOKEN_URL_OVERRIDE` is
-* set. A login someone else made is never replaced.
+* machine and the credential to the service, which Codex calls when
+* `CODEX_REFRESH_TOKEN_URL_OVERRIDE` is set. A login someone else made is never replaced,
+* nor one a release before named credentials wrote: its two-part composite is not ours.
 */
 const placeCodex = (home, login, identity) => {
 	const existing = readJsonObject(authFile$1(home));
-	if (Object.keys(existing).length > 0 && ownTokens(existing) === void 0) throw new Error(`${authFile$1(home)} was not written by clankercreds; refusing to replace it`);
+	if (Object.keys(existing).length > 0 && ownTokens(existing) === void 0) throw new Error(`${authFile$1(home)} was not written by clankercreds, or by a release before credentials were named; refusing to replace it. If clankercreds wrote it, remove it and sync again`);
 	writeJson(authFile$1(home), {
 		auth_mode: "chatgpt",
 		OPENAI_API_KEY: null,
 		tokens: {
 			id_token: login.idToken,
 			access_token: login.accessToken,
-			refresh_token: formatCodexRefreshToken(identity.clientId, identity.key),
+			refresh_token: formatCodexRefreshToken(identity.clientId, login.credential, identity.key),
 			account_id: login.accountId
 		},
 		last_refresh: (/* @__PURE__ */ new Date()).toISOString()
@@ -533,8 +514,21 @@ const clientId = (home, machineIdFile = clankerboxMachineId) => {
 	writeAtomic(file, `${generated}\n`);
 	return generated;
 };
-/** The access token `token` last fetched for pi. The client's own copy; no tool reads it. */
-const accessTokenFile = (home) => join(stateDirectory(home), "access-token");
+/**
+* pi's access token, and the ChatGPT credential it is of, which `token` renews it from. The
+* client's own copy; no tool reads it.
+*/
+const HeldToken = Schema.Struct({
+	credential: Schema.String,
+	accessToken: Schema.String
+});
+/** Encoding writes the schema's fields only, so pi's whole entry may be passed. */
+const HeldTokenJson = Schema.fromJsonString(HeldToken);
+const heldTokenFile = (home) => join(stateDirectory(home), "access-token");
+/** The copy as `token` reads it. One that does not name its credential is no copy. */
+const readHeldToken = (home) => Option.getOrUndefined(Schema.decodeUnknownOption(HeldTokenJson)(readText(heldTokenFile(home))));
+const writeHeldToken = (home, held) => writeAtomic(heldTokenFile(home), `${Schema.encodeSync(HeldTokenJson)(held)}\n`);
+const removeHeldToken = (home) => remove(heldTokenFile(home));
 //#endregion
 //#region src/place/pi.ts
 const modelsFile = (home) => join(home, ".pi/agent/models.json");
@@ -552,10 +546,11 @@ const refuseStoredLogin = (home) => {
 };
 /**
 * Only the key is ours; every other provider setting in the file is kept. The token goes
-* first, so whatever stops the key, `token` never answers for a login the bundle dropped.
+* first, with its credential, so whatever stops the key, `token` never answers for a
+* credential the config no longer names.
 */
-const placePi = (home, accessToken) => {
-	writeAtomic(accessTokenFile(home), `${accessToken}\n`);
+const placePi = (home, held) => {
+	writeHeldToken(home, held);
 	refuseStoredLogin(home);
 	const models = readJsonObject(modelsFile(home));
 	const providers = objectAt(models, "providers", modelsFile(home));
@@ -594,7 +589,7 @@ const removeEntry = (home) => {
 * is left alone when it is someone else's.
 */
 const removePi = (home) => {
-	remove(accessTokenFile(home));
+	removeHeldToken(home);
 	return removeEntry(home);
 };
 //#endregion
@@ -617,11 +612,14 @@ const placements = {
 		remove: (config) => removeCodex(config.home)
 	},
 	pi: {
-		place: (config, _identity, [credential]) => placePi(config.home, credential.accessToken),
+		place: (config, _identity, [credential]) => placePi(config.home, credential),
 		remove: (config) => removePi(config.home)
 	}
 };
-/** What the bundle carries of one type is placed; a type it does not carry is undone. */
+/** What this client places; anything else delivered, a token or a type it does not know, is skipped. */
+const isPlaceable = (credential) => Object.hasOwn(placements, credential.type);
+const placeableTypes = knownTypes.filter((type) => Object.hasOwn(placements, type));
+/** What the delivery carries of one type is placed; a type it does not carry is undone. */
 const settle = (config, identity, known, type) => {
 	const credentials = known.filter((credential) => credential.type === type);
 	if (credentials.length === 0) return placements[type].remove(config) ? "removed" : void 0;
@@ -629,25 +627,51 @@ const settle = (config, identity, known, type) => {
 	return "placed";
 };
 /**
-* Idempotent: the whole bundle is fetched and placed every time, and every type it does
-* not carry is undone, whether or not a previous sync placed it. Nothing on disk changes
-* until the service has answered, so an unreachable service leaves every file as it was.
-* Each type stands alone: a file that is not ours to touch stops its own type only.
+* What a machine holds one of, named as the operator stored it: a GitHub token per host, one
+* Claude token, and one ChatGPT login, which arrives as a codex and a pi entry under one name.
+*/
+const slot = (credential) => {
+	switch (credential.type) {
+		case "gh": return `GitHub credentials for ${credential.host}`;
+		case "claude": return "Claude credentials";
+		case "codex":
+		case "pi": return "ChatGPT credentials";
+	}
+};
+/**
+* Two credentials for one slot would leave the machine holding whichever came last: the
+* whole sync is refused before anything is written.
+*/
+const oneEach = (placed) => {
+	const claimed = /* @__PURE__ */ new Map();
+	for (const credential of placed) {
+		const other = claimed.get(slot(credential));
+		if (other !== void 0 && other !== credential.credential) throw new Error(`${other} and ${credential.credential} are both ${slot(credential)}; a machine holds one, so config.json must name only one of them`);
+		claimed.set(slot(credential), credential.credential);
+	}
+	return placed;
+};
+/**
+* Idempotent: every credential the config names is fetched and placed every time, and every
+* type the delivery does not carry is undone, whether or not a previous sync placed it.
+* Nothing on disk changes until the service has answered, so an unreachable service leaves
+* every file as it was. Each type stands alone: a file that is not ours to touch stops its
+* own type only.
 */
 const sync = async (config) => {
 	const identity = {
 		clientId: clientId(config.home),
 		key: config.key
 	};
-	const bundle = await fetchBundle(config, identity.clientId);
-	const known = bundle.credentials.filter((credential) => isKnownType(credential.type));
+	const delivery = await fetchDelivery(config, identity.clientId);
+	const known = oneEach(delivery.credentials.filter(isPlaceable));
 	const report = {
 		placed: new Array(),
 		removed: new Array(),
-		skipped: bundle.credentials.flatMap(({ type }) => isKnownType(type) ? [] : [type]),
+		skipped: delivery.credentials.flatMap((credential) => isPlaceable(credential) ? [] : [credential.type]),
 		failed: new Array()
 	};
-	for (const type of knownTypes) try {
+	for (const type of placeableTypes) try {
 		const outcome = settle(config, identity, known, type);
 		if (outcome !== void 0) report[outcome].push(type);
 	} catch (error) {
@@ -666,20 +690,24 @@ const margin = 3e5;
 const remaining = (jwt) => (claimsOf(jwt).exp ?? 0) * 1e3 - Date.now();
 /**
 * pi runs this on every model call, so the common path is one small file read. The token is
-* the client's own copy, placed by sync, so no other tool's file is read or written. Near
-* expiry, or with no copy, the service is asked again; an outage does not take a
-* still-valid token away.
+* the client's own copy, placed by sync with the credential it is of, so no other tool's file
+* is read or written. Near expiry the service is asked again for that credential; an outage
+* does not take a still-valid token away. With no copy there is nothing to renew.
 */
 const accessToken = async (config) => {
-	const file = accessTokenFile(config.home);
-	const held = readText(file)?.trim();
-	if (held && remaining(held) > margin) return held;
+	const held = readHeldToken(config.home);
+	if (held === void 0) throw new Error("no ChatGPT credential is placed for pi; run `clankercreds sync`");
+	if (remaining(held.accessToken) > margin) return held.accessToken;
 	try {
-		const { accessToken: fresh } = await fetchCodexLogin(config, clientId(config.home));
-		if (held && readText(file)?.trim() === held) writeAtomic(file, `${fresh}\n`);
+		const { accessToken: fresh } = await fetchCodexLogin(config, clientId(config.home), held.credential);
+		const current = readHeldToken(config.home);
+		if (current?.credential === held.credential && current.accessToken === held.accessToken) writeHeldToken(config.home, {
+			credential: held.credential,
+			accessToken: fresh
+		});
 		return fresh;
 	} catch (error) {
-		if (error instanceof Unreachable && held && remaining(held) > 0) return held;
+		if (error instanceof Unreachable && remaining(held.accessToken) > 0) return held.accessToken;
 		throw error;
 	}
 };
@@ -687,12 +715,13 @@ const accessToken = async (config) => {
 //#region src/main.ts
 const usage = `Usage: clankercreds <command>
 
-  sync    Fetch this machine's bundle and place each credential where its tool expects it.
+  sync    Fetch the credentials the config names and place each where its tool expects it.
   token   Print the current ChatGPT access token, for pi.
+  admin   Administer the service over its admin port: \`clankercreds admin --help\`.
 `;
 const runSync = async () => {
 	const report = await sync(loadConfig());
-	for (const type of report.skipped) console.error(`warning: skipped unknown credential type "${type}"; update clankercreds`);
+	for (const type of report.skipped) console.error(`warning: skipped credential type "${type}", which this client does not place; if it is new, update clankercreds`);
 	for (const type of report.placed) console.log(`placed ${type}`);
 	for (const type of report.removed) console.log(`removed ${type}`);
 	for (const { type, message } of report.failed) console.error(`error: ${type}: ${message}`);
@@ -711,6 +740,10 @@ const commandFor = (name) => {
 	}
 };
 const main = async () => {
+	if (process.argv[2] === "admin") {
+		(await import("./admin-DC0cTmmT.mjs")).run(process.argv.slice(2));
+		return;
+	}
 	const command = commandFor(process.argv[2]);
 	if (command === void 0) {
 		console.error(usage);

package/dist/shared-C56uw1xx.mjs

@@ -0,0 +1,127 @@
+import { Context, Data, Option, Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+Data.TaggedError("Unauthorized");
+/**
+* The issuer could not be reached, so the credential could not be decided: a 503, not a
+* refusal. A resource's descriptor declares it,
+* `Authentication.make("notes.Login", CurrentPrincipal, { error: ProviderUnavailable })`.
+* Its public response is the schema. Diagnostic causes are internal, non-enumerable fields.
+*/
+var ProviderUnavailable = class extends Schema.TaggedError()("ProviderUnavailable", { operation: Schema.String }, { httpApiStatus: 503 }) {
+	constructor(options) {
+		super({ operation: options.operation });
+		Object.defineProperty(this, "cause", { value: options.cause });
+	}
+};
+Data.TaggedError("InsufficientScope");
+Schema.TaggedError()("ConfigurationError", { message: Schema.String });
+//#endregion
+//#region ../../node_modules/.pnpm/@gjermundgaraba+clankerauth-sdk@0.16.0_@gjermundgaraba+effect-actions@0.11.0_effect@4.0.2__effect@4.0.2/node_modules/@gjermundgaraba/clankerauth-sdk/dist/session.js
+/**
+* The identity a browser page needs, without any verification code. This entry point is
+* browser-safe: it declares the identity a protected contract states, the `whoami` contract
+* and the issuer's sign-out URL, so contracts, bindings and pages import it directly, and a
+* server answers `Whoami` with its resource's `session`.
+*/
+/**
+* The caller: what a protected contract states, `caller: CurrentPrincipal`, and what an
+* authentication descriptor proves,
+* `Authentication.make("notes.Login", CurrentPrincipal, { error: ProviderUnavailable })`.
+* Remotely, the resource's provider gives it per request, from the verified credential; on
+* a trusted local surface, the host gives it the process, `Notes.local(subject)`.
+*/
+var CurrentPrincipal = class extends Context.Service()("@clankerauth/CurrentPrincipal") {};
+/** The verified credential behind a request, as the resource server read it. */
+const Principal = Schema.Struct({
+	subject: Schema.NonEmptyString,
+	issuer: Schema.NonEmptyString,
+	scopes: Schema.Array(Schema.String)
+});
+Action.make("whoami", {
+	description: "The verified subject, issuer and scopes behind this request's credential.",
+	readOnly: true,
+	caller: CurrentPrincipal,
+	success: Principal
+});
+//#endregion
+//#region ../../packages/api/src/shared.ts
+/**
+* What a credential of the clankercreds resource may carry. `machine` admits the
+* public actions and nothing else; `read` and `admin` admit the admin actions.
+*/
+const scopes = {
+	machine: "clankercreds:machine",
+	read: "clankercreds:read",
+	admin: "clankercreds:admin"
+};
+/**
+* What was asked for does not exist: a key, credential or sign-in by that name, or a
+* credential the calling machine key is not granted, which it is not told apart from one
+* that does not exist.
+*/
+var NotFound = class extends Schema.TaggedError()("NotFound", { message: Schema.String }, { httpApiStatus: 404 }) {};
+/** The change collides with what is stored: a taken name, or a credential still in use. */
+var Conflict = class extends Schema.TaggedError()("Conflict", { message: Schema.String }, { httpApiStatus: 409 }) {};
+/** The login is dead, or was never completed. Only a new sign-in revives it. */
+var NeedsSignIn = class extends Schema.TaggedError()("NeedsSignIn", { message: Schema.String }, { httpApiStatus: 409 }) {};
+/** The provider could not be reached and no valid token is held. Waiting helps; retrying now does not. */
+var UpstreamUnavailable = class extends Schema.TaggedError()("UpstreamUnavailable", { message: Schema.String }, { httpApiStatus: 503 }) {};
+/**
+* Credential names: lowercase labels, because they are typed by hand and are
+* identities. SQLite compares them case-sensitively, so mixed case would let `GitHub-Main`
+* and `github-main` be two credentials.
+*/
+const Name = Schema.String.check(Schema.isPattern(/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/));
+/**
+* What an operator stores a value for: a GitHub token, a Claude token, or `token`, any other
+* service's API key, which a service such as clankerusage reads and no machine places.
+*/
+const SecretKind = Schema.Literals([
+	"gh",
+	"claude",
+	"token"
+]);
+/**
+* What a sign-in creates and the service keeps refreshed. The refresh token never leaves
+* the service; only access tokens are delivered.
+*/
+const LoginKind = Schema.Literals([
+	"chatgpt",
+	"grok",
+	"cursor"
+]);
+const CredentialKind = Schema.Literals([...SecretKind.literals, ...LoginKind.literals]);
+/** A GitHub host, lowercase: it is written into `gh`'s and git's configuration as is. */
+const Host = Schema.String.check(Schema.isPattern(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/), Schema.isMaxLength(253));
+/**
+* The machine's self-generated label. It identifies nothing; it only groups audit rows.
+* It excludes `:` because the Codex refresh token is `<clientId>:<credential>:<key>`.
+*/
+const ClientId = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_-]{1,64}$/));
+const Claims = Schema.Struct({
+	exp: Schema.optionalKey(Schema.Number),
+	email: Schema.optionalKey(Schema.String),
+	"https://api.openai.com/auth": Schema.optionalKey(Schema.Struct({ chatgpt_account_id: Schema.optionalKey(Schema.String) }))
+});
+/**
+* The claims of a JWT, unverified: they are read for their timing, email and, in OpenAI's,
+* account, never trusted for anything. Anything unreadable is simply no claims.
+*/
+const claimsOf = (jwt) => {
+	const payload = Buffer.from(jwt.split(".")[1] ?? "", "base64url").toString("utf8");
+	const claims = Schema.decodeUnknownOption(Schema.fromJsonString(Claims))(payload);
+	return Option.match(claims, {
+		onNone: () => ({
+			exp: void 0,
+			email: void 0,
+			accountId: void 0
+		}),
+		onSome: (value) => ({
+			exp: value.exp,
+			email: value.email,
+			accountId: value["https://api.openai.com/auth"]?.chatgpt_account_id
+		})
+	});
+};
+//#endregion
+export { LoginKind as a, NotFound as c, claimsOf as d, scopes as f, Host as i, SecretKind as l, ProviderUnavailable as m, Conflict as n, Name as o, CurrentPrincipal as p, CredentialKind as r, NeedsSignIn as s, ClientId as t, UpstreamUnavailable as u };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gjermundgaraba/clankercreds",
-  "version": "0.2.0",
-  "description": "The machine client of clankercreds: fetches a bundle of credentials and places each where its tool expects it.",
+  "version": "0.4.0",
+  "description": "The clankercreds command: a machine client that fetches the credentials its config names and places each where its tool expects it, and the operator's admin commands.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,17 +19,19 @@
     "access": "public"
   },
   "dependencies": {
-    "@gjermundgaraba/effect-actions": "0.10.0",
-    "effect": "4.0.0",
+    "@effect/platform-node": "4.0.2",
+    "@effect/platform-node-shared": "4.0.2",
+    "@gjermundgaraba/effect-actions": "0.11.0",
+    "effect": "4.0.2",
     "yaml": "2.9.1"
   },
   "devDependencies": {
-    "@clankercreds/api": "0.0.0",
-    "@gjermundgaraba/clankerauth-sdk": "0.13.0",
-    "@types/node": "26.6.2",
+    "@gjermundgaraba/clankerauth-sdk": "0.16.0",
+    "@gjermundgaraba/clankercreds-api": "0.4.0",
+    "@types/node": "26.6.5",
     "typescript": "7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0",
-    "vite-plus": "1.0.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
+    "vite-plus": "1.1.0"
   },
   "engines": {
     "node": ">=26"