@gjermundgaraba/clankercreds 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gjermund Garaba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/main.mjs

@@ -0,0 +1,739 @@
+#!/usr/bin/env node
+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 { Option, Predicate, Schema } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+import * as ActionHttpClient from "@gjermundgaraba/effect-actions/ActionHttpClient";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+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;
+	}
+};
+/**
+* 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;
+};
+/** 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)
+	};
+};
+//#endregion
+//#region ../../node_modules/.pnpm/@gjermundgaraba+clankerauth-sdk@0.9.0_@gjermundgaraba+effect-actions@0.7.0_effect@4.0.0-rc.117_/node_modules/@gjermundgaraba/clankerauth-sdk/dist/errors.js
+/**
+* Every refusal this package produces, as schemas. This entry point is browser-safe:
+* a shared contract declares these on its surface and a browser client decodes them,
+* without pulling token verification or its cryptography into the bundle.
+*
+* Schemas define public responses. Diagnostic causes are internal, non-enumerable fields.
+*/
+var Unauthorized = class extends Schema.TaggedError()("Unauthorized", { message: Schema.String }, { httpApiStatus: 401 }) {
+	constructor(options) {
+		super({ message: options.message });
+		Object.defineProperty(this, "cause", { value: options.cause });
+	}
+};
+var RateLimited = class extends Schema.TaggedError()("RateLimited", { message: Schema.String }, { httpApiStatus: 429 }) {};
+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 });
+	}
+};
+/**
+* A verified credential lacks one scope the requested access needs. It names only
+* the missing scope, so a refusal never enumerates the resource's permissions.
+*/
+var InsufficientScope = class extends Schema.TaggedError()("InsufficientScope", { scope: Schema.String }, { httpApiStatus: 403 }) {};
+Schema.TaggedError()("ConfigurationError", { message: Schema.String });
+/**
+* What verification, admission and the authorization hook refuse with — one list, so a
+* surface declares `errors: authenticationErrors` and answers every refusal the same way.
+*/
+const authenticationErrors = [
+	Unauthorized,
+	InsufficientScope,
+	RateLimited,
+	ProviderUnavailable
+];
+//#endregion
+//#region ../../packages/api/src/bundle.ts
+const GhCredential = Schema.Struct({
+	type: Schema.Literal("gh"),
+	host: Schema.String,
+	token: Schema.String
+});
+const ClaudeCredential = Schema.Struct({
+	type: Schema.Literal("claude"),
+	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.
+*/
+const CodexLogin = Schema.Struct({
+	accessToken: Schema.String,
+	idToken: Schema.String,
+	accountId: Schema.String
+});
+const CodexCredential = Schema.Struct({
+	type: Schema.Literal("codex"),
+	...CodexLogin.fields
+});
+/**
+* The access token `clankercreds token` answers pi with until it is near expiry: pi asks the
+* command on every model call, and the command asks the service only after that.
+*/
+const PiCredential = Schema.Struct({
+	type: Schema.Literal("pi"),
+	accessToken: Schema.String
+});
+/**
+* The client is baked into images, 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.
+*/
+const TypedCredential = Schema.Union([
+	GhCredential,
+	ClaudeCredential,
+	CodexCredential,
+	PiCredential
+]);
+/** The types this build knows, derived from the union so there is one list. */
+const knownTypes = TypedCredential.members.map((member) => member.fields.type.literal);
+const isKnownType = (type) => knownTypes.some((known) => known === type);
+/**
+* What the service may send that this client does not know yet. It decodes instead of
+* failing, so the client can skip it with a warning. A known type that fails its own
+* 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])) });
+//#endregion
+//#region ../../packages/api/src/shared.ts
+/** The caller asked for something the service cannot do with the input given. */
+var BadRequest = class extends Schema.TaggedError()("BadRequest", { message: Schema.String }, { httpApiStatus: 400 }) {};
+/**
+* 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 }) {};
+/** The request could not be represented on the wire; never a caller-fixable failure. */
+var InternalError = class extends Schema.TaggedError()("InternalError", { message: Schema.String }, { httpApiStatus: 500 }) {};
+/** Transport failures answer with the same public errors handlers use. */
+const schemaError = {
+	invalid: {
+		schema: BadRequest,
+		make: () => new BadRequest({ message: "The request does not match the action's input." })
+	},
+	internal: {
+		schema: InternalError,
+		make: () => new InternalError({ message: "The response could not be encoded." })
+	}
+};
+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) }))
+});
+/**
+* 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.
+*/
+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
+//#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 = ActionGroup.make({
+	name: "machine",
+	schemaError
+}, Action.make("bundle", {
+	access: "read",
+	description: "Fetch the typed credentials of the bundle bound to the calling key.",
+	input: Schema.Struct({ clientId: ClientId }),
+	success: Bundle,
+	errors: [NotFound],
+	mcp: false
+}), Action.make("codexLogin", {
+	access: "read",
+	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,
+	errors: [
+		NotFound,
+		NeedsSignIn,
+		UpstreamUnavailable
+	],
+	mcp: false
+}));
+/**
+* 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.
+*/
+var CodexRefreshRejected = class extends Schema.TaggedError()("CodexRefreshRejected", { error: Schema.Struct({
+	code: Schema.String,
+	message: Schema.String
+}) }, { httpApiStatus: 401 }) {};
+var CodexRefreshUnavailable = class extends Schema.TaggedError()("CodexRefreshUnavailable", { error: Schema.Struct({
+	code: Schema.String,
+	message: Schema.String
+}) }, { httpApiStatus: 503 }) {};
+/**
+* Codex's own refresh request, the one request whose shape is not ours. The refresh-token
+* field carries `<clientId>:<key>`, so this group authenticates in its handler instead of
+* through bearer middleware. The answer leaves `refresh_token` out, so Codex keeps the
+* composite it has.
+*/
+const Codex = ActionGroup.make({ name: "codex" }, Action.make("refresh", {
+	access: "read",
+	description: "Answer Codex's token refresh with the bundle's current ChatGPT tokens.",
+	input: Schema.Struct({
+		grant_type: Schema.Literal("refresh_token"),
+		refresh_token: Schema.String,
+		client_id: Schema.optionalKey(Schema.String),
+		scope: Schema.optionalKey(Schema.String)
+	}),
+	success: Schema.Struct({
+		access_token: Schema.String,
+		id_token: Schema.String
+	}),
+	errors: [CodexRefreshRejected, CodexRefreshUnavailable],
+	mcp: false
+}));
+/** `<clientId>:<key>`. Client ids exclude `:`, so the key is the rest. */
+const formatCodexRefreshToken = (clientId, key) => `${clientId}:${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 MachineHttp = ActionHttp.make({
+	apiPath: "/v1",
+	errors: authenticationErrors
+}, Machine);
+ActionHttp.make({ apiPath: "/v1" }, Codex);
+Object.keys(ActionGroup.contracts(Machine, Codex)).map((key) => `/v1/${key.replace(".", "/")}`);
+//#endregion
+//#region src/service.ts
+/** The service answered and said no. Retrying the same request will not help. */
+var Refused = class extends Error {};
+/** No answer worth acting on. Whatever the machine already holds stays in place. */
+var Unreachable = class extends Error {};
+/**
+* The deadline covers the whole request, the body included. It matters most to `token`:
+* pi gives the command about ten seconds, and a hang would cost it a token it already holds.
+*/
+const connect = (config, deadlineMs) => ActionHttpClient.promise(MachineHttp, {
+	baseUrl: config.service,
+	transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken(config.key)),
+	fetch: (input, init) => {
+		const deadline = AbortSignal.timeout(deadlineMs);
+		const signal = init?.signal ? AbortSignal.any([init.signal, deadline]) : deadline;
+		return fetch(input, {
+			...init,
+			signal
+		});
+	}
+});
+/**
+* The key's own refusals and the declared answers are refusals. Whatever is left is an
+* outage: transport, upstream, a broken answer, or a service that never answers.
+*/
+const classify = (error) => {
+	if (error instanceof Unauthorized) return new Refused("The machine key was refused. It may have been revoked.");
+	if (error instanceof InsufficientScope) return new Refused("The machine key does not carry the machine scope.");
+	if (error instanceof NotFound || error instanceof BadRequest || error instanceof NeedsSignIn) return new Refused(error.message);
+	return new Unreachable(error instanceof Error ? error.message : String(error));
+};
+const refuse = (error) => Promise.reject(classify(error));
+const fetchBundle = (config, clientId) => connect(config, 3e4).machine.bundle({ clientId }).catch(refuse);
+const fetchCodexLogin = (config, clientId) => connect(config, 5e3).machine.codexLogin({ clientId }).catch(refuse);
+//#endregion
+//#region src/place/claude.ts
+const settingsFile = (home) => join(home, ".claude/settings.json");
+const variable = "CLAUDE_CODE_OAUTH_TOKEN";
+/**
+* The mark that the token next to it is ours: a token alone cannot say who set it. It
+* sits in the same `env` block, where Claude Code passes it through and nothing reads it.
+*/
+const mark$1 = "CLANKERCREDS_CLAUDE";
+/** Only the variable and its mark are ours; every other setting in the file is kept. */
+const placeClaude = (home, token) => {
+	const settings = readJsonObject(settingsFile(home));
+	const env = objectAt(settings, "env", settingsFile(home));
+	if (variable in env && !(mark$1 in env)) throw new Error(`${variable} in ${settingsFile(home)} was not set by clankercreds; refusing to replace it`);
+	writeJson(settingsFile(home), {
+		...settings,
+		env: {
+			...env,
+			[variable]: token,
+			[mark$1]: "placed"
+		}
+	});
+};
+/** True when our marked variable was there. A token someone else set is left alone. */
+const removeClaude = (home) => {
+	const settings = readJsonObject(settingsFile(home));
+	const env = settings["env"];
+	if (!isJsonObject(env) || !(mark$1 in env)) return false;
+	const { [variable]: _removed, [mark$1]: _mark, ...rest } = env;
+	const { env: _env, ...others } = settings;
+	writeJson(settingsFile(home), Object.keys(rest).length === 0 ? others : {
+		...others,
+		env: rest
+	});
+	return true;
+};
+//#endregion
+//#region src/place/codex.ts
+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.
+*/
+const ownTokens = (auth) => {
+	const tokens = auth["tokens"];
+	if (!isJsonObject(tokens)) return void 0;
+	const { access_token, refresh_token } = tokens;
+	if (typeof access_token !== "string" || typeof refresh_token !== "string") return void 0;
+	if (parseCodexRefreshToken(refresh_token) === void 0) return void 0;
+	return {
+		accessToken: access_token,
+		refreshToken: refresh_token
+	};
+};
+/**
+* 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.
+*/
+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`);
+	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),
+			account_id: login.accountId
+		},
+		last_refresh: (/* @__PURE__ */ new Date()).toISOString()
+	});
+};
+/** True when a file of ours was there. A login someone else wrote is left alone. */
+const removeCodex = (home) => ownTokens(readJsonObject(authFile$1(home))) === void 0 ? false : remove(authFile$1(home));
+//#endregion
+//#region src/place/gh.ts
+const hostsFile = (configHome) => join(configHome, "gh/hosts.yml");
+/** Git's XDG config, so `~/.gitconfig` is never touched. */
+const gitConfig = (configHome) => join(configHome, "git/config");
+/**
+* `hosts.yml` maps each host to its settings. An entry holding this key is ours to replace
+* and to remove; `gh` keeps keys it does not know when it rewrites the file, and every other
+* host in it is left as it was, though not always byte for byte.
+*/
+const mark = "clankercreds";
+const isOurs = ({ value }) => isMap(value) && value.get(mark) === true;
+/** The file's entries. What is not valid YAML, or not a map of hosts, is not ours to replace. */
+const readHosts = (path) => {
+	const doc = parseDocument(readText(path) ?? "");
+	if (doc.errors.length > 0 || doc.contents !== null && !isMap(doc.contents)) throw new Error(`${path} is not a map of hosts; refusing to replace it`);
+	const hosts = isMap(doc.contents) ? doc.contents : new YAMLMap(doc.schema);
+	doc.contents = hosts;
+	return {
+		doc,
+		hosts
+	};
+};
+/** gh's own layout: four-space indents, and no long line folded. */
+const hostsText = (doc) => doc.toString({
+	indent: 4,
+	lineWidth: 0
+});
+const begin = "# >>> clankercreds";
+const end = "# <<< clankercreds";
+/** Everything outside the marked block belongs to someone else and is kept byte for byte. */
+const withoutBlock = (text) => {
+	const start = text.indexOf(begin);
+	const stop = text.indexOf(end);
+	if (start === -1 || stop === -1) return text;
+	return `${text.slice(0, start)}${text.slice(stop + 18).replace(/^\n/, "")}`;
+};
+/** The empty `helper =` resets any inherited helper, so only `gh` answers for these hosts. */
+const credentialHelpers = (hosts) => [
+	begin,
+	...hosts.flatMap((host) => [
+		`[credential "https://${host}"]`,
+		"	helper =",
+		"	helper = !gh auth git-credential"
+	]),
+	end,
+	""
+].join("\n");
+const appended = (text, addition) => `${text}${text === "" || text.endsWith("\n") ? "" : "\n"}${addition}`;
+/** Our entries go at the end of the file, one per host, whatever was there before. */
+const placeGh = (configHome, credentials) => {
+	const { doc, hosts } = readHosts(hostsFile(configHome));
+	hosts.items = hosts.items.filter((pair) => !isOurs(pair));
+	const foreign = credentials.find(({ host }) => hosts.has(host));
+	if (foreign !== void 0) throw new Error(`${foreign.host} in ${hostsFile(configHome)} was not set by clankercreds; refusing to replace it`);
+	for (const { host, token } of credentials) hosts.set(host, doc.createNode({
+		oauth_token: token,
+		git_protocol: "https",
+		[mark]: true
+	}));
+	writeAtomic(hostsFile(configHome), hostsText(doc));
+	const config = withoutBlock(readText(gitConfig(configHome)) ?? "");
+	writeAtomic(gitConfig(configHome), appended(config, credentialHelpers(credentials.map(({ host }) => host))));
+};
+/** True when something of ours was there. Safe to run when nothing was placed. */
+const removeGh = (configHome) => {
+	const file = hostsFile(configHome);
+	const { doc, hosts } = readHosts(file);
+	const kept = hosts.items.filter((pair) => !isOurs(pair));
+	const owned = kept.length < hosts.items.length;
+	if (owned) {
+		hosts.items = kept;
+		if (kept.length === 0) remove(file);
+		else writeAtomic(file, hostsText(doc));
+	}
+	const existing = readText(gitConfig(configHome));
+	if (existing === void 0) return owned;
+	const config = withoutBlock(existing);
+	if (config === existing) return owned;
+	if (config.trim() === "") remove(gitConfig(configHome));
+	else writeAtomic(gitConfig(configHome), config);
+	return true;
+};
+//#endregion
+//#region src/state.ts
+const stateDirectory = (home) => join(home, ".local/state/clankercreds");
+/**
+* A label for the audit log, generated on the machine on first use. It must never be
+* created during an image build, or every machine from that image would share it.
+*/
+const clientId = (home) => {
+	const file = join(stateDirectory(home), "client-id");
+	const existing = readText(file)?.trim();
+	if (existing !== void 0 && existing !== "") return existing;
+	const generated = `m_${randomBytes(9).toString("base64url")}`;
+	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");
+//#endregion
+//#region src/place/pi.ts
+const modelsFile = (home) => join(home, ".pi/agent/models.json");
+const authFile = (home) => join(home, ".pi/agent/auth.json");
+const provider = "openai-codex";
+/** pi runs this on every model call; the client answers from its own cached token. It is the mark. */
+const command = "!clankercreds token";
+/**
+* pi checks its own credential store before a configured key, so a stored ChatGPT login
+* would win over the command and refresh against OpenAI behind the service's back. It is
+* someone's login, so it is not removed: the sync stops until they sign pi out.
+*/
+const refuseStoredLogin = (home) => {
+	if (provider in readJsonObject(authFile(home))) throw new Error(`pi is signed in to ChatGPT in ${authFile(home)}; sign it out, or the login would bypass the service`);
+};
+/**
+* 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.
+*/
+const placePi = (home, accessToken) => {
+	writeAtomic(accessTokenFile(home), `${accessToken}\n`);
+	refuseStoredLogin(home);
+	const models = readJsonObject(modelsFile(home));
+	const providers = objectAt(models, "providers", modelsFile(home));
+	const existing = objectAt(providers, provider, modelsFile(home));
+	if ("apiKey" in existing && existing["apiKey"] !== command) throw new Error(`the ${provider} key in ${modelsFile(home)} was not set by clankercreds; refusing to replace it`);
+	writeJson(modelsFile(home), {
+		...models,
+		providers: {
+			...providers,
+			[provider]: {
+				...existing,
+				apiKey: command
+			}
+		}
+	});
+};
+const removeEntry = (home) => {
+	const models = readJsonObject(modelsFile(home));
+	const providers = models["providers"];
+	if (!isJsonObject(providers)) return false;
+	const existing = providers[provider];
+	if (!isJsonObject(existing) || existing["apiKey"] !== command) return false;
+	const { apiKey: _removed, ...rest } = existing;
+	const { [provider]: _provider, ...others } = providers;
+	writeJson(modelsFile(home), {
+		...models,
+		providers: Object.keys(rest).length === 0 ? others : {
+			...others,
+			[provider]: rest
+		}
+	});
+	return true;
+};
+/**
+* True when our entry was there. `token`'s copy goes with it, whoever owns the key, which
+* is left alone when it is someone else's.
+*/
+const removePi = (home) => {
+	remove(accessTokenFile(home));
+	return removeEntry(home);
+};
+//#endregion
+//#region src/sync.ts
+/**
+* Where each type goes and how it is undone. Removal touches only what this client wrote
+* and says whether anything was there. A type missing here does not compile.
+*/
+const placements = {
+	gh: {
+		place: (config, _identity, credentials) => placeGh(config.configHome, credentials),
+		remove: (config) => removeGh(config.configHome)
+	},
+	claude: {
+		place: (config, _identity, [credential]) => placeClaude(config.home, credential.token),
+		remove: (config) => removeClaude(config.home)
+	},
+	codex: {
+		place: (config, identity, [credential]) => placeCodex(config.home, credential, identity),
+		remove: (config) => removeCodex(config.home)
+	},
+	pi: {
+		place: (config, _identity, [credential]) => placePi(config.home, credential.accessToken),
+		remove: (config) => removePi(config.home)
+	}
+};
+/** What the bundle 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;
+	placements[type].place(config, identity, credentials);
+	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.
+*/
+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 report = {
+		placed: new Array(),
+		removed: new Array(),
+		skipped: bundle.credentials.flatMap(({ type }) => isKnownType(type) ? [] : [type]),
+		failed: new Array()
+	};
+	for (const type of knownTypes) try {
+		const outcome = settle(config, identity, known, type);
+		if (outcome !== void 0) report[outcome].push(type);
+	} catch (error) {
+		report.failed.push({
+			type,
+			message: error instanceof Error ? error.message : String(error)
+		});
+	}
+	return report;
+};
+//#endregion
+//#region src/token.ts
+/** Codex's own margin: a token with less than this left is refreshed before it is used. */
+const margin = 3e5;
+/** The token's own expiry, unverified: it only decides when to ask the service again. */
+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.
+*/
+const accessToken = async (config) => {
+	const file = accessTokenFile(config.home);
+	const held = readText(file)?.trim();
+	if (held && remaining(held) > margin) return held;
+	try {
+		const { accessToken: fresh } = await fetchCodexLogin(config, clientId(config.home));
+		if (held && readText(file)?.trim() === held) writeAtomic(file, `${fresh}\n`);
+		return fresh;
+	} catch (error) {
+		if (error instanceof Unreachable && held && remaining(held) > 0) return held;
+		throw error;
+	}
+};
+//#endregion
+//#region src/main.ts
+const usage = `Usage: clankercreds <command>
+
+  sync    Fetch this machine's bundle and place each credential where its tool expects it.
+  token   Print the current ChatGPT access token, for pi.
+`;
+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.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}`);
+	if (report.failed.length > 0) process.exitCode = 1;
+	else if (report.placed.length === 0 && report.removed.length === 0) console.log("nothing to place");
+};
+/** Only the token reaches stdout: pi takes the whole output as the key. */
+const runToken = async () => {
+	process.stdout.write(`${await accessToken(loadConfig())}\n`);
+};
+const commandFor = (name) => {
+	switch (name) {
+		case "sync": return runSync;
+		case "token": return runToken;
+		default: return;
+	}
+};
+const main = async () => {
+	const command = commandFor(process.argv[2]);
+	if (command === void 0) {
+		console.error(usage);
+		process.exitCode = 2;
+		return;
+	}
+	try {
+		await command();
+	} catch (error) {
+		if (error instanceof Unreachable) {
+			console.error(`error: the service could not be reached; existing files were kept`);
+			console.error(`  ${error.message}`);
+		} else if (error instanceof Error) console.error(`error: ${error.message}`);
+		else throw error;
+		process.exitCode = 1;
+	}
+};
+await main();
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@gjermundgaraba/clankercreds",
+  "version": "0.1.0",
+  "description": "The machine client of clankercreds: fetches a bundle of credentials and places each where its tool expects it.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gjermundgaraba/clankercreds.git",
+    "directory": "apps/cli"
+  },
+  "bin": {
+    "clankercreds": "./dist/main.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@gjermundgaraba/effect-actions": "0.7.0",
+    "effect": "4.0.0-rc.117",
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "@clankercreds/api": "0.0.0",
+    "@gjermundgaraba/clankerauth-sdk": "0.9.0",
+    "@types/node": "26.6.2",
+    "typescript": "7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0-rc.1",
+    "vite-plus": "1.0.0-rc.1"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "scripts": {
+    "test": "vp test --passWithNoTests",
+    "check": "vp check",
+    "build": "vp pack"
+  }
+}