Two processes that minted at once left the forge two tokens by one name, and a token kept in a file in the runtime state is a plain state. Both accounts' tokens (mesh-tools, mesh-packages) are now the module's own secrets in the vault, written through the seat mesh-vault's own-put and read through its get, sealed to the reading process's key. A refused or expired (token-ttl) token is minted again only by the holder of the lease mint in the state token-lease (mint-lease); each mint is named <account>-<generation>, and the token it replaces is deleted by id only after own-put landed. The Go bundles read their tokens through get at start and at secret-changed; the MESH_GITEA_*_TOKEN_FILE words go. forge_token_lease reads the lease and each token's age, never the token. Builds: design 47 H2 §808, §822; H-A-407, H-A-422, H-A-426, H-A-430 (1)
580 lines
30 KiB
TypeScript
580 lines
30 KiB
TypeScript
// The token the forge's tools and watcher authenticate with — and where it comes from.
|
|
//
|
|
// Nobody configures it. The forge is raised by the mesh, so there is no operator holding a token to
|
|
// paste in, and pasting one into settings would put a secret in the inventory in plaintext. What
|
|
// the mesh does deliver is the admin account: a login the manifest names and a password the vault
|
|
// minted and the host unsealed into a file (novox/hq ADR 0086). That account is enough to mint a
|
|
// token, so the module mints its own (hq issue 100, the forge's tools), for each of its two accounts, the tools'
|
|
// (`mesh-tools`) and the package seats' (`mesh-packages`):
|
|
//
|
|
// - **kept as a secret, the module's own in the vault** (design 47 H2 §808, §822; H-A-422, H-A-426): written through
|
|
// the seat `mesh-vault`'s two-step sealed write `own-put` under the account's name, so the vault keeps it as
|
|
// `module/gitea/<account>`, its newest generation only, and read through the seat's `get`, sealed to this process's
|
|
// key. Never a file in the runtime state and never plain in a state: the forge hands a token's value out exactly
|
|
// once, and the vault is where the module keeps what it must not lose;
|
|
// - **one name per mint**, `<account>-<generation>`, the generation the one this own-put makes (get's generation plus
|
|
// one; 1 when the vault holds none; H-A-430 (1)). The token minted is written through own-put first, and only then
|
|
// is the token it replaces deleted at the forge, by its id: no moment is without a valid token, and a mint that
|
|
// fails leaves the old one standing. The first mint replaces the tokens the module kept before under the account's
|
|
// old fixed name;
|
|
// - **minted by one process at a time** (§808). The runtime starts each of the bundle's entrypoints as a process of its
|
|
// own (novox/hq ADR 0193), and two that minted at once left the forge two tokens by one name (the 2026-10-14 outage).
|
|
// A process the forge refuses first reads the vault's token; only when the refused token is the vault's current one
|
|
// does it take the lease — the key `mint` in the module's state `token-lease`, created only, living `mint-lease` (a
|
|
// setting, default 60 s) — and mint. A process that finds the lease taken waits for that key to change, at most the
|
|
// lease, then reads the vault again; past it, the lease has expired and the waiter creates it itself;
|
|
// - **minted again when older than `token-ttl`** (a setting, default 24 hours), its age the vault's `changed-at`;
|
|
// - minted for the account, not the administrator (novox/hq ADR 0365 §2, issue 469): the administrator's login mints
|
|
// it for the account, after making that account and its team, and deletes any token named `mesh-tools` the
|
|
// administrator itself still holds — the token the tools used before.
|
|
//
|
|
// An explicitly configured token still wins, and is never minted over: if it is rejected, that is
|
|
// reported, not repaired — somebody chose it.
|
|
//
|
|
// The token is never logged. Lines say that one was minted, reused or renewed, and under which name;
|
|
// never what it is.
|
|
|
|
import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync } from "node:fs";
|
|
import { randomBytes } from "node:crypto";
|
|
import { join } from "node:path";
|
|
import { generateKeyPair, open, sealAnonymous, type Box, type KeyPair } from "@novox/mesh-sdk/seal";
|
|
import { broker } from "@novox/mesh-sdk/messaging";
|
|
import { askRuntime } from "@novox/mesh-sdk/runtime";
|
|
import { state, type State } from "@novox/mesh-sdk/state";
|
|
import { setUpToolsAccount, TOOLS_ACCOUNT, type AdminCall } from "./tools-account.js";
|
|
import { keepMainRules } from "./mainrules.js";
|
|
import { durationMs } from "./taken.js";
|
|
|
|
/** The tools' token's old fixed name in the forge's list, the one the admin's own token carried too (ADR 0365 §2). */
|
|
export const TOKEN_NAME = "mesh-tools";
|
|
|
|
/** The module whose own secrets the vault keeps its tokens as (§822: the module named by the caller's account). */
|
|
export const VAULT_MODULE = "gitea";
|
|
|
|
/** The vault's name of an account's token: `module/gitea/<account>` (H-A-426). */
|
|
export function vaultName(account: string): string {
|
|
return `module/${VAULT_MODULE}/${account}`;
|
|
}
|
|
|
|
/** The forge's name of an account's token of one generation: `<account>-<generation>` (H-A-422 (2)). */
|
|
export function mintName(account: string, generation: number): string {
|
|
return `${account}-${generation}`;
|
|
}
|
|
|
|
/** The state the mint's lease is kept in, and its one key (§808, §820). */
|
|
export const LEASE_STATE = "token-lease";
|
|
export const LEASE_KEY = "mint";
|
|
|
|
/** token-ttl's and mint-lease's defaults (§808). */
|
|
export const TOKEN_TTL_DEFAULT = "24h";
|
|
export const MINT_LEASE_DEFAULT = "60s";
|
|
|
|
/** A setting the node-engine composes as `MESH_CONFIG_<NAME>`, a duration, in milliseconds; the default when unset, and
|
|
* when it is no duration (said). */
|
|
export function settingMs(env: NodeJS.ProcessEnv, setting: string, fallback: string, log: (line: string) => void = () => {}): number {
|
|
const raw = env[`MESH_CONFIG_${setting.toUpperCase().replace(/-/g, "_")}`];
|
|
const dflt = durationMs(fallback)!;
|
|
if (raw === undefined || raw.trim() === "") return dflt;
|
|
const ms = durationMs(raw);
|
|
if (ms === null) {
|
|
log(`the setting ${setting} is ${JSON.stringify(raw)}, no duration: the default ${fallback} holds`);
|
|
return dflt;
|
|
}
|
|
return ms;
|
|
}
|
|
|
|
/**
|
|
* The least the fifteen tools and the watcher need (gitea's route groups, 1.20+ scoped tokens):
|
|
* write:repository — create/delete repositories, pull requests (list/get/open/merge);
|
|
* write:issue — issues, comments, labels;
|
|
* read:package — the package registry's reads by the Go bundle (cmd/package-registry): the package seats'
|
|
* held, versions and the retention's survey (design 51: a read-only tool token; the
|
|
* writes go with the packages account's own token, packages-account.ts);
|
|
* read:user — GET /user/repos, which the watcher's poll and gitea_list_repos both call.
|
|
* It sits under the `user` category despite listing repositories, not `repository`
|
|
* — confirmed against the running forge (1.27.3), which answered
|
|
* `required=[read:user]` to a token carrying only the other two.
|
|
*
|
|
* **Not write:admin** (novox/hq ADR 0266). It was here so a person could settle the forge's users through
|
|
* `gitea_api` (novox/hq 229); whoever may call a tool includes agents, and the forge's administration is the
|
|
* operator's. The provisioner settles users with the admin account's own login (GiteaAdmin), never this token.
|
|
*
|
|
* A token kept from before a scope was added lacks it: the forge answers such a call with
|
|
* `403 token does not have at least one of required scope(s)`, and the client treats that like a
|
|
* 401 — the source re-mints by name, with the whole list, and the call is retried once.
|
|
*/
|
|
export const TOKEN_SCOPES: readonly string[] = ["write:repository", "write:issue", "read:user", "read:package"];
|
|
|
|
/** Where a client's token comes from, and what to do when the forge says it is wrong. */
|
|
export interface TokenSource {
|
|
/** The token to authenticate with now; minted, read or configured. */
|
|
current(): Promise<string>;
|
|
/** The forge answered 401 to `rejected`, or 403 for a scope it lacks. A fresh token, or a plain error when there is nothing to renew with. */
|
|
renew(rejected: string): Promise<string>;
|
|
}
|
|
|
|
/** A token somebody set — in settings or the environment. Never minted over. */
|
|
export class ConfiguredToken implements TokenSource {
|
|
constructor(private readonly token: string) {}
|
|
|
|
async current(): Promise<string> {
|
|
return this.token;
|
|
}
|
|
|
|
async renew(): Promise<string> {
|
|
throw new Error(
|
|
"the forge rejected the configured Gitea token (401). It was set explicitly (settings or GITEA_TOKEN), " +
|
|
"so the module does not mint over it — fix it, or unset it and the module mints its own",
|
|
);
|
|
}
|
|
}
|
|
|
|
/** The forge would not take the admin account: it refused the login the mesh holds (design 47 H2 §776). Said as the
|
|
* forge's refusal, never as an account to create: whether the forge is away is the seat's to judge (seat.ts). */
|
|
export class AdminRefused extends Error {
|
|
constructor(admin: string, status: number) {
|
|
super(`the forge refuses the mesh's admin account "${admin}" (${status})`);
|
|
this.name = "AdminRefused";
|
|
}
|
|
}
|
|
|
|
/** A token as the vault holds it: the value, the generation and when it changed (`get`'s answer, opened). */
|
|
export interface VaultToken {
|
|
readonly token: string;
|
|
readonly generation: number;
|
|
readonly changedAt: string;
|
|
}
|
|
|
|
/** The vault as the minter reaches it: the seat `mesh-vault`'s `get` and `own-put` (§808, §822). */
|
|
export interface TokenVault {
|
|
/** The account's token the vault holds, or null when it holds none. */
|
|
get(account: string): Promise<VaultToken | null>;
|
|
/** Write the account's token as the module's own; answers the generation the vault kept. */
|
|
put(account: string, token: string): Promise<number>;
|
|
}
|
|
|
|
/** The lease `mint` in the state `token-lease` (§808). */
|
|
export interface MintLease {
|
|
/** Create the lease for `holder`, living `ms`; false when another holds it. */
|
|
take(holder: string, ms: number): Promise<boolean>;
|
|
/** The lease's holder and since when, or null when nobody holds it. */
|
|
read(): Promise<{ holder: string; since: string } | null>;
|
|
/** Delete the lease, when `holder` still holds it. */
|
|
release(holder: string): Promise<void>;
|
|
/** Resolves when the lease's key changes (deleted, or written again), or after `ms`, whichever is first. */
|
|
changed(ms: number): Promise<void>;
|
|
}
|
|
|
|
/** The vault's words when it holds no secret by the name asked (mesh-vault's Get). */
|
|
const HOLDS_NONE = /the vault holds no secret named/;
|
|
|
|
/** The vault over the bus: `get` sealed to this process's own key, made once a process; `own-put` in its two steps. */
|
|
export function vaultOverBus(request: (verb: string, body: unknown) => Promise<unknown> = (v, b) => broker().request(v, b)): TokenVault {
|
|
let keys: KeyPair | undefined;
|
|
return {
|
|
async get(account) {
|
|
keys ??= generateKeyPair();
|
|
let answer: { generation?: number; "changed-at"?: string; sealed?: Box };
|
|
try {
|
|
answer = (await request("seat:mesh-vault.get", { name: vaultName(account), public_key: keys.publicKey })) as typeof answer;
|
|
} catch (err) {
|
|
if (HOLDS_NONE.test(err instanceof Error ? err.message : String(err))) return null;
|
|
throw err;
|
|
}
|
|
if (!answer?.sealed) throw new Error(`the vault answered no sealed ${vaultName(account)}`);
|
|
return { token: open(answer.sealed, keys.privateKey), generation: answer.generation ?? 0, changedAt: answer["changed-at"] ?? "" };
|
|
},
|
|
async put(account, token) {
|
|
const opened = (await request("seat:mesh-vault.own-put", { name: account })) as { call?: string; seal_to?: string };
|
|
if (!opened?.call || !opened.seal_to) throw new Error(`the vault opened no own-put call for ${vaultName(account)}`);
|
|
const kept = (await request("seat:mesh-vault.own-put", { call: opened.call, sealed: sealAnonymous(token, opened.seal_to) })) as { generation?: number };
|
|
return kept?.generation ?? 0;
|
|
},
|
|
};
|
|
}
|
|
|
|
/** The runtime's refusal of a create whose key has a value (mesh-sdk's CODE_CHANGED). */
|
|
const CODE_CHANGED = -32010;
|
|
|
|
/** The lease in the module's state `token-lease` over the runtime: a create with the lease as its time to live, and one
|
|
* watch of the key a process, handing each change to the waiters. */
|
|
export function leaseOverState(st: State<{ holder: string; since: string }> = state(LEASE_STATE),
|
|
ask: (method: string, params: unknown) => Promise<unknown> = askRuntime): MintLease {
|
|
const waiters = new Set<() => void>();
|
|
let watching: Promise<void> | undefined;
|
|
return {
|
|
async take(holder, ms) {
|
|
try {
|
|
await ask("mesh/state.create", { state: LEASE_STATE, key: LEASE_KEY, value: { holder, since: new Date().toISOString() },
|
|
ttl_seconds: Math.max(1, Math.ceil(ms / 1000)) });
|
|
return true;
|
|
} catch (err) {
|
|
if ((err as { code?: number }).code === CODE_CHANGED) return false;
|
|
throw err;
|
|
}
|
|
},
|
|
async read() {
|
|
return (await st.get(LEASE_KEY))?.value ?? null;
|
|
},
|
|
async release(holder) {
|
|
if ((await st.get(LEASE_KEY))?.value?.holder === holder) await st.delete(LEASE_KEY);
|
|
},
|
|
async changed(ms) {
|
|
watching ??= st.watch((change) => {
|
|
if (!change.current) for (const wake of [...waiters]) wake();
|
|
}, { key: LEASE_KEY });
|
|
await watching;
|
|
await new Promise<void>((resolve) => {
|
|
const wake = () => { clearTimeout(timer); waiters.delete(wake); resolve(); };
|
|
const timer = setTimeout(wake, ms);
|
|
waiters.add(wake);
|
|
// Released between the refused create and this wait: nothing to wait for.
|
|
void st.get(LEASE_KEY).then((e) => { if (!e) wake(); }, () => {});
|
|
});
|
|
},
|
|
};
|
|
}
|
|
|
|
export interface MintedTokenOptions {
|
|
/** The forge, e.g. http://127.0.0.1:3000. */
|
|
readonly url: string;
|
|
/** The admin login the manifest names. */
|
|
readonly admin: string;
|
|
/** The file the host unsealed the admin password into (ADR 0086). Read at mint time, so a rotation takes. */
|
|
readonly passwordFile: string;
|
|
/** The account the token is minted for, and the vault name it is kept under (H-A-426). */
|
|
readonly account: string;
|
|
/** The token's fixed name before a name per mint: the first mint deletes the account's tokens by it (H-A-430 (1)). */
|
|
readonly oldName: string;
|
|
readonly scopes?: readonly string[];
|
|
/** Run with the admin's password before each mint: makes the account and its team (tools-account.ts). */
|
|
readonly setUp?: (password: string) => Promise<void>;
|
|
/** Where the module keeps its token, and the mint's lease (§808). */
|
|
readonly vault: TokenVault;
|
|
readonly lease: MintLease;
|
|
/** token-ttl and mint-lease, in milliseconds (§808). */
|
|
readonly ttlMs?: number;
|
|
readonly leaseMs?: number;
|
|
/** Who holds the lease when this process does: the node and the process. */
|
|
readonly holder?: string;
|
|
/** The module's runtime state directory, where a retirement of the admin's old token that failed is remembered. */
|
|
readonly stateDir?: string;
|
|
readonly now?: () => Date;
|
|
readonly log?: (line: string) => void;
|
|
readonly fetch?: typeof fetch;
|
|
}
|
|
|
|
/** The token the module mints for itself, kept in the vault and renewed when the forge rejects it. */
|
|
export class MintedToken implements TokenSource {
|
|
private held: VaultToken | null = null;
|
|
private inflight: Promise<string> | null = null;
|
|
private readonly scopes: readonly string[];
|
|
private readonly ttlMs: number;
|
|
private readonly leaseMs: number;
|
|
private readonly holder: string;
|
|
private readonly now: () => Date;
|
|
private readonly log: (line: string) => void;
|
|
private readonly fetchImpl: typeof fetch;
|
|
|
|
constructor(private readonly opts: MintedTokenOptions) {
|
|
this.scopes = opts.scopes ?? TOKEN_SCOPES;
|
|
this.ttlMs = opts.ttlMs ?? durationMs(TOKEN_TTL_DEFAULT)!;
|
|
this.leaseMs = opts.leaseMs ?? durationMs(MINT_LEASE_DEFAULT)!;
|
|
this.holder = opts.holder ?? `${process.env.MESH_NODE || "unknown"}/${process.pid}`;
|
|
this.now = opts.now ?? (() => new Date());
|
|
this.log = opts.log ?? ((line) => console.log(`[gitea] ${line}`));
|
|
this.fetchImpl = opts.fetch ?? fetch;
|
|
}
|
|
|
|
/** The account this source mints for. */
|
|
get account(): string {
|
|
return this.opts.account;
|
|
}
|
|
|
|
/**
|
|
* The tools' token from the runtime's environment: the forge's URL, the admin login and password file the manifest
|
|
* hands the runtime, the vault and the lease over the bus. Throws, naming what is missing, rather than hand back a
|
|
* source that cannot mint. One source per account and runtime state in a process: two would each renew on a 401.
|
|
*/
|
|
static fromEnv(url: string, env: NodeJS.ProcessEnv = process.env): MintedToken {
|
|
const account = env.MESH_GITEA_TOOLS_USER || TOOLS_ACCOUNT;
|
|
const { admin, passwordFile } = adminFromEnv(env, "no Gitea token, and nothing to mint one with — set GITEA_TOKEN, or");
|
|
const key = `${account} ${env.MESH_GITEA_STATE_DIR ?? ""}`;
|
|
const shared = MintedToken.shared.get(key);
|
|
if (shared) return shared;
|
|
if (account === admin) throw new Error(`MESH_GITEA_TOOLS_USER names the admin account "${admin}"; the tools act as an account of their own (novox/hq ADR 0365)`);
|
|
const source = new MintedToken({
|
|
...MintedToken.settingsFromEnv(env), url, admin, passwordFile, account, oldName: TOKEN_NAME,
|
|
// GiteaAdmin is loaded when first used: client.ts imports this file.
|
|
setUp: async (password) => {
|
|
const { GiteaAdmin } = await import("./client.js");
|
|
await setUpToolsAccount(new GiteaAdmin(url, admin, password), account, () => randomBytes(24).toString("base64url"), keepMainRules(env));
|
|
},
|
|
});
|
|
MintedToken.shared.set(key, source);
|
|
return source;
|
|
}
|
|
|
|
private static readonly shared = new Map<string, MintedToken>();
|
|
|
|
/** What every account's source takes from the environment: the vault and lease over the bus, the two settings. */
|
|
static settingsFromEnv(env: NodeJS.ProcessEnv): Pick<MintedTokenOptions, "vault" | "lease" | "ttlMs" | "leaseMs" | "stateDir"> {
|
|
const log = (line: string) => console.log(`[gitea] ${line}`);
|
|
return {
|
|
vault: sharedVault(), lease: sharedLease(),
|
|
ttlMs: settingMs(env, "token-ttl", TOKEN_TTL_DEFAULT, log), leaseMs: settingMs(env, "mint-lease", MINT_LEASE_DEFAULT, log),
|
|
stateDir: env.MESH_GITEA_STATE_DIR || undefined,
|
|
};
|
|
}
|
|
|
|
/** The token held, read from the vault when none is, minted when the vault holds none or one older than token-ttl. */
|
|
async current(): Promise<string> {
|
|
if (this.held !== null && !this.expired(this.held)) return this.held.token;
|
|
const kept = await this.opts.vault.get(this.opts.account);
|
|
if (kept === null) return this.mint("the vault holds no token for this account — minting one", null);
|
|
if (this.expired(kept)) return this.mint(`the vault's token is older than token-ttl (${this.ttlMs / 1000}s) — minting one`, kept.token);
|
|
if (this.held === null) {
|
|
this.log(`reusing the token the vault keeps as ${vaultName(this.opts.account)} (generation ${kept.generation})`);
|
|
// A retirement of the admin's old token that failed after the mint is tried again, once a process.
|
|
if (this.retireFile && existsSync(this.retireFile)) await this.retireAdmin().catch((err) => this.log(`${err}`));
|
|
}
|
|
this.held = kept;
|
|
return kept.token;
|
|
}
|
|
|
|
async renew(rejected: string): Promise<string> {
|
|
// Another caller already renewed while this one was in flight with the old token.
|
|
if (this.held !== null && this.held.token !== rejected) return this.held.token;
|
|
// A refusal of a stale token mints nothing: the vault's newer one is used (§808).
|
|
const kept = await this.opts.vault.get(this.opts.account);
|
|
if (kept !== null && kept.token !== rejected) {
|
|
this.held = kept;
|
|
this.log(`the forge rejected the token held; the vault's ${vaultName(this.opts.account)} is newer (generation ${kept.generation}) — reusing it`);
|
|
return kept.token;
|
|
}
|
|
this.held = null;
|
|
return this.mint("the forge rejected the vault's token — minting a fresh one", rejected);
|
|
}
|
|
|
|
/** What the forge's scoped tokens say when a kept token predates a scope the tools now need. */
|
|
static lacksScope(status: number, body: string): boolean {
|
|
return status === 403 && /required scope/i.test(body);
|
|
}
|
|
|
|
private expired(t: VaultToken): boolean {
|
|
const at = Date.parse(t.changedAt);
|
|
return Number.isFinite(at) && this.now().getTime() - at > this.ttlMs;
|
|
}
|
|
|
|
/**
|
|
* One mint at a time: concurrent calls in this process share it, and a mint in another process is waited for (the
|
|
* lease). Holding the lease, the vault is read again: a token there that is not `stale` (the one refused or expired)
|
|
* was minted by the process that held the lease before — it is used, not minted over.
|
|
*/
|
|
private mint(why: string, stale: string | null): Promise<string> {
|
|
if (this.inflight === null) {
|
|
this.log(why);
|
|
this.inflight = this.leased(stale).finally(() => {
|
|
this.inflight = null;
|
|
});
|
|
}
|
|
return this.inflight;
|
|
}
|
|
|
|
private async leased(stale: string | null): Promise<string> {
|
|
for (;;) {
|
|
if (await this.opts.lease.take(this.holder, this.leaseMs)) {
|
|
try {
|
|
const kept = await this.opts.vault.get(this.opts.account);
|
|
if (kept !== null && kept.token !== stale && !this.expired(kept)) {
|
|
this.held = kept;
|
|
this.log(`another process minted it meanwhile — reusing the vault's generation ${kept.generation}`);
|
|
return kept.token;
|
|
}
|
|
return await this.doMint(kept);
|
|
} finally {
|
|
await this.opts.lease.release(this.holder).catch((err) =>
|
|
this.log(`the mint lease could not be deleted; it ends with mint-lease — ${err instanceof Error ? err.message : err}`));
|
|
}
|
|
}
|
|
const other = await this.opts.lease.read().catch(() => null);
|
|
this.log(`another process holds the mint lease${other ? ` (${other.holder} since ${other.since})` : ""} — waiting for it, at most mint-lease (${this.leaseMs / 1000}s)`);
|
|
await this.opts.lease.changed(this.leaseMs);
|
|
const kept = await this.opts.vault.get(this.opts.account);
|
|
if (kept !== null && kept.token !== stale && !this.expired(kept)) {
|
|
this.held = kept;
|
|
this.log(`the process that held the mint lease minted generation ${kept.generation} — reusing it`);
|
|
return kept.token;
|
|
}
|
|
}
|
|
}
|
|
|
|
/** The admin password, read now. */
|
|
private password(): string {
|
|
try {
|
|
return readFileSync(this.opts.passwordFile, "utf8").replace(/\n$/, "");
|
|
} catch (err) {
|
|
throw new Error(`cannot read the admin password at ${this.opts.passwordFile}: ${(err as Error).message}`);
|
|
}
|
|
}
|
|
|
|
/** One call to the forge's API with the admin login. */
|
|
private adminCall(password = this.password()): AdminCall {
|
|
const authorization = "Basic " + Buffer.from(`${this.opts.admin}:${password}`).toString("base64");
|
|
const api = `${this.opts.url.replace(/\/+$/, "")}/api/v1`;
|
|
const admin: AdminCall = async (method, path, body) => {
|
|
const res = await this.fetchImpl(api + path, {
|
|
method,
|
|
headers: { "Content-Type": "application/json", Authorization: authorization },
|
|
...(body === undefined ? {} : { body: JSON.stringify(body) }),
|
|
});
|
|
const text = await res.text();
|
|
let parsed: any = null;
|
|
if (text) {
|
|
try { parsed = JSON.parse(text); } catch { parsed = text; }
|
|
}
|
|
return { status: res.status, body: parsed };
|
|
};
|
|
return admin;
|
|
}
|
|
|
|
/** Where a retirement of the admin's old token that failed is remembered, to be tried again (retireAdmin). */
|
|
private get retireFile(): string | null {
|
|
return this.opts.stateDir ? join(this.opts.stateDir, `${this.opts.account}.retire-admin`) : null;
|
|
}
|
|
|
|
/**
|
|
* The admin's own token named `mesh-tools` goes: what the tools used before must not outlive the move (novox/hq ADR
|
|
* 0365 §2). Run after the account's token is minted and kept, so a failure here never leaves the tools without a
|
|
* token: it is said, remembered, and tried again when a process next reads the vault's token.
|
|
*/
|
|
private async retireAdmin(admin: AdminCall = this.adminCall()): Promise<void> {
|
|
if (this.opts.oldName !== TOKEN_NAME) return;
|
|
try {
|
|
const retired = await this.dropNamed(admin, `/users/${encodeURIComponent(this.opts.admin)}/tokens`, this.opts.admin, TOKEN_NAME);
|
|
if (retired > 0) this.log(`deleted ${retired} token(s) named "${TOKEN_NAME}" the admin account "${this.opts.admin}" held: the tools act as "${this.opts.account}" now`);
|
|
if (this.retireFile) rmSync(this.retireFile, { force: true });
|
|
} catch (err) {
|
|
if (this.retireFile) {
|
|
mkdirSync(this.opts.stateDir!, { recursive: true, mode: 0o700 });
|
|
writeFileSync(this.retireFile, `${new Date().toISOString()}\n`, { mode: 0o600 });
|
|
}
|
|
this.log(`FAILED to delete the token(s) named "${TOKEN_NAME}" the admin account "${this.opts.admin}" holds — tried again at the next start: ${(err as Error).message}`);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Mint `<account>-<generation>` (the generation this own-put makes), write it through own-put, and only then delete
|
|
* at the forge, by id, the token it replaces: `replaced`'s by its name, or at the first mint the tokens under the
|
|
* account's old fixed name (H-A-422 (2), H-A-430 (1)).
|
|
*/
|
|
private async doMint(replaced: VaultToken | null): Promise<string> {
|
|
const password = this.password();
|
|
const admin = this.adminCall(password);
|
|
const account = this.opts.account;
|
|
const tokens = `/users/${encodeURIComponent(account)}/tokens`;
|
|
const generation = (replaced?.generation ?? 0) + 1;
|
|
const name = mintName(account, generation);
|
|
|
|
// The account and its team first (novox/hq ADR 0365 §2): a failure here fails the mint, tried again at the next call.
|
|
const me = await admin("GET", "/user");
|
|
if (me.status === 401 || me.status === 403) throw new AdminRefused(this.opts.admin, me.status);
|
|
await this.opts.setUp?.(password);
|
|
|
|
let res = await admin("POST", tokens, { name, scopes: this.scopes });
|
|
if (res.status === 401 || res.status === 403) throw new AdminRefused(this.opts.admin, res.status);
|
|
if (res.status === 400 || res.status === 422) {
|
|
// A mint of this generation whose own-put never landed left its token at the forge, unused: deleted by its id
|
|
// (gitea refuses a delete by a name held twice), then minted again.
|
|
await this.dropNamed(admin, tokens, account, name, true);
|
|
res = await admin("POST", tokens, { name, scopes: this.scopes });
|
|
}
|
|
if (res.status !== 201 && res.status !== 200) {
|
|
throw new Error(`Gitea POST /users/${account}/tokens: ${res.status} ${detail(res.body)}`);
|
|
}
|
|
const token = typeof res.body?.sha1 === "string" ? res.body.sha1 : null;
|
|
if (!token) throw new Error(`Gitea POST /users/${account}/tokens: ${res.status} but no token in the reply`);
|
|
|
|
const kept = await this.opts.vault.put(account, token);
|
|
if (kept !== generation) this.log(`the vault kept ${vaultName(account)} at generation ${kept}, the forge names it ${name}`);
|
|
this.held = { token, generation: kept, changedAt: this.now().toISOString() };
|
|
this.log(`minted ${name} for "${account}" (${this.scopes.join(", ")}), kept in the vault as ${vaultName(account)}`);
|
|
|
|
// Only now, with the new token kept, does the one it replaces go.
|
|
const gone = replaced ? mintName(account, replaced.generation) : this.opts.oldName;
|
|
try {
|
|
const dropped = await this.dropNamed(admin, tokens, account, gone);
|
|
if (dropped > 0) this.log(`deleted ${dropped} token(s) named "${gone}" "${account}" held: ${name} replaces them`);
|
|
} catch (err) {
|
|
this.log(`FAILED to delete the token "${gone}" ${name} replaces; the forge holds both until the next mint — ${(err as Error).message}`);
|
|
}
|
|
await this.retireAdmin(admin);
|
|
return token;
|
|
}
|
|
|
|
/** Delete every token named `name` an account holds, each by its id; answers how many. */
|
|
private async dropNamed(admin: AdminCall, tokens: string, account: string, name: string, replacing = false): Promise<number> {
|
|
const held: number[] = [];
|
|
for (let page = 1; page <= 100; page++) {
|
|
const listed = await admin("GET", `${tokens}?page=${page}&limit=50`);
|
|
if (listed.status !== 200 || !Array.isArray(listed.body)) {
|
|
throw new Error(`Gitea GET /users/${account}/tokens: ${listed.status} ${detail(listed.body)}`);
|
|
}
|
|
if (listed.body.length === 0) break;
|
|
for (const t of listed.body) if (t?.name === name && typeof t.id === "number") held.push(t.id);
|
|
}
|
|
if (replacing) this.log(`the forge already holds ${held.length} token(s) named "${name}" — deleting each by its id and minting one`);
|
|
for (const id of held) {
|
|
const dropped = await admin("DELETE", `${tokens}/${id}`);
|
|
if (dropped.status !== 204 && dropped.status !== 404) {
|
|
throw new Error(`Gitea DELETE /users/${account}/tokens/${id} (named ${name}): ${dropped.status} ${detail(dropped.body)}`);
|
|
}
|
|
}
|
|
return held.length;
|
|
}
|
|
}
|
|
|
|
/** The admin login and password file the manifest hands the runtime, or an error naming what is missing. */
|
|
export function adminFromEnv(env: NodeJS.ProcessEnv, missingWords: string): { admin: string; passwordFile: string } {
|
|
const admin = env.MESH_GITEA_ADMIN_USER;
|
|
const passwordFile = env.MESH_GITEA_ADMIN_PASSWORD_FILE;
|
|
const missing = [admin ? null : "MESH_GITEA_ADMIN_USER", passwordFile ? null : "MESH_GITEA_ADMIN_PASSWORD_FILE"]
|
|
.filter((v): v is string => v !== null);
|
|
if (missing.length) throw new Error(`${missingWords} ${missing.join(", ")}`);
|
|
return { admin: admin!, passwordFile: passwordFile! };
|
|
}
|
|
|
|
// One vault and one lease a process, shared by both accounts' sources: one key and one watch.
|
|
let vaultOnce: TokenVault | undefined;
|
|
let leaseOnce: MintLease | undefined;
|
|
function sharedVault(): TokenVault {
|
|
return (vaultOnce ??= vaultOverBus());
|
|
}
|
|
function sharedLease(): MintLease {
|
|
return (leaseOnce ??= leaseOverState());
|
|
}
|
|
|
|
/** The tool forge_token_lease's reading (§808): the lease's holder and since when, and each account's token age, read
|
|
* from the vault's `changed-at`; never the token. */
|
|
export async function tokenLease(vault: TokenVault, lease: MintLease, accounts: readonly string[], now: Date = new Date()) {
|
|
const held = await lease.read();
|
|
const out: { account: string; vault: string; generation?: number; "changed-at"?: string; "age-seconds"?: number; held: boolean }[] = [];
|
|
for (const account of accounts) {
|
|
const t = await vault.get(account);
|
|
out.push(t === null ? { account, vault: vaultName(account), held: false } : {
|
|
account, vault: vaultName(account), held: true, generation: t.generation, "changed-at": t.changedAt,
|
|
"age-seconds": Math.max(0, Math.floor((now.getTime() - Date.parse(t.changedAt)) / 1000)),
|
|
});
|
|
}
|
|
return { lease: held === null ? { held: false } : { held: true, holder: held.holder, since: held.since }, tokens: out };
|
|
}
|
|
|
|
/** The vault and the lease this process mints through, for the tool forge_token_lease. */
|
|
export function processVaultAndLease(): { vault: TokenVault; lease: MintLease } {
|
|
return { vault: sharedVault(), lease: sharedLease() };
|
|
}
|
|
|
|
function detail(body: unknown): string {
|
|
return typeof body === "string" ? body : JSON.stringify(body);
|
|
}
|