The forge mints its own API token with the admin account the vault delivers

The runtime beside the forge served 0 tools: GiteaClient.fromEnv required a token
(settings or MESH_GITEA_TOKEN), nobody had one to give — the mesh raised the forge —
and putting one in settings would store a secret in plaintext in the inventory. So
the fifteen tools registered nothing and the watcher logged "not watching".

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 (ADR 0086). That is
enough to mint a token, so the module does (hq issue 100, the forge's tools):
POST /users/{admin}/tokens over basic auth, scoped to write:repository and
write:issue — the least the tools and the repo watcher need — kept at 0600 in the
module's own state (/var/lib/mesh/gitea/state, a new directory resource the runtime
mounts writable), read back on the next start, and minted afresh when the forge
answers 401 to it or the kept file is gone. A forge whose data came from the
predecessor has no mesh-admin: that is reported in plain words on every poll until
it clears, once per reason, not crash-looped. A configured token still wins and is
never minted over.

The mint happens on the first call, not at registration: a contributor is
synchronous, and a forge not yet answering must not keep the runtime from serving.
One source per kept file in a process, or the watcher and the tools would each
renew on a 401 and drop the other's token by name.

modules/gitea/client.ts

@@ -4,6 +4,7 @@
 // does.
 
 import { readFileSync } from "node:fs";
+import { ConfiguredToken, MintedToken, type TokenSource } from "./token.js";
 
 /** A repository, trimmed to what the mesh cares about. */
 export interface GiteaRepo {
@@ -53,44 +54,60 @@ function meshConfig(file?: string): Record<string, string> {
 
 export class GiteaClient {
   readonly baseUrl: string;
-  private cachedUsername: string | null = null;
+  private readonly tokens: TokenSource;
 
-  constructor(
-    url: string,
-    private readonly token: string,
-  ) {
+  /** A token given as a string is one somebody configured; a source decides for itself (token.ts). */
+  constructor(url: string, token: string | TokenSource) {
     this.baseUrl = url.replace(/\/+$/, "");
+    this.tokens = typeof token === "string" ? new ConfiguredToken(token) : token;
   }
 
   /**
-   * Build from the module's resolved environment. URL and token come from MESH_GITEA_URL /
-   * MESH_GITEA_TOKEN (the mesh's own names), falling back to the bare GITEA_* names and, for the
-   * URL, to the forge's loopback port. A token is required — without one there is no authenticated
-   * call to make, so this throws rather than hand back a client that fails on first use.
+   * Build from the module's resolved environment. The URL comes from MESH_GITEA_URL (the mesh's own
+   * name), falling back to the bare GITEA_URL and to the forge's loopback port. The token, in order:
+   * one configured in settings or the environment (MESH_GITEA_TOKEN / GITEA_TOKEN), which wins; else
+   * one the module mints for itself with the admin account the vault delivered and keeps in its own
+   * state (token.ts; hq issue 100). Throws only when neither is possible, naming what is missing,
+   * rather than hand back a client that fails on first use.
    */
   static fromEnv(env: NodeJS.ProcessEnv = process.env): GiteaClient {
     const cfg = meshConfig(env.MESH_GITEA_CONFIG_FILE);
     const url = cfg.url ?? env.MESH_GITEA_URL ?? env.GITEA_URL ?? `http://127.0.0.1:${env.GITEA_PORT ?? "3000"}`;
-    const token = cfg.token ?? env.MESH_GITEA_TOKEN ?? env.GITEA_TOKEN;
-    if (!token) throw new Error("no Gitea token — set MESH_GITEA_TOKEN");
-    return new GiteaClient(url, token);
+    const configured = cfg.token ?? env.MESH_GITEA_TOKEN ?? env.GITEA_TOKEN;
+    if (configured) return new GiteaClient(url, new ConfiguredToken(configured));
+    return new GiteaClient(url, MintedToken.fromEnv(url, env));
   }
 
+  /**
+   * One authenticated call. A 401 is the forge saying the token is not one it knows — the case
+   * after the forge's data was restored, or after somebody revoked it — so the source is asked to
+   * renew once and the call is repeated with the new token. A configured token has nothing to renew
+   * with, and its source says so.
+   */
   private async request<T = unknown>(path: string, options: RequestInit = {}): Promise<T> {
-    const res = await fetch(`${this.baseUrl}/api/v1${path}`, {
-      ...options,
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `token ${this.token}`,
-        ...(options.headers as Record<string, string> | undefined),
-      },
-    });
+    let token = await this.tokens.current();
+    let res = await this.send(path, options, token);
+    if (res.status === 401) {
+      token = await this.tokens.renew(token);
+      res = await this.send(path, options, token);
+    }
     if (!res.ok) throw new Error(`Gitea API ${path}: ${res.status} ${await res.text()}`);
     if (res.status === 204) return null as T;
     const text = await res.text();
     return (text ? JSON.parse(text) : null) as T;
   }
 
+  private send(path: string, options: RequestInit, token: string): Promise<Response> {
+    return fetch(`${this.baseUrl}/api/v1${path}`, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `token ${token}`,
+        ...(options.headers as Record<string, string> | undefined),
+      },
+    });
+  }
+
   /** Generic authenticated API call — the escape hatch for endpoints without a dedicated method.
    *  Path is relative to /api/v1. */
   async api<T = unknown>(path: string, options: RequestInit = {}): Promise<T> {