@ggui-ai/cli 0.1.0-rc.1

package/dist/internal/oidc-token.js

@@ -0,0 +1,351 @@
+/**
+ * OIDC token resolution chain for sigstore signing.
+ *
+ * Public-gadget publishing signs with sigstore's keyless flow — Fulcio
+ * exchanges a short-lived OIDC identity-token for an ephemeral signing
+ * cert, then Rekor anchors the resulting signature in the transparency
+ * log. The CLI's job is to *get an OIDC token* from one of four sources;
+ * the actual sign call lives behind `signBundleSigstore` (gadget-signing).
+ *
+ * Precedence (highest first):
+ *
+ *   1. `--identity-token <jwt>` flag (matches cosign convention).
+ *   2. `GGUI_OIDC_TOKEN` env var.
+ *   3. GitHub Actions ambient OIDC — when `ACTIONS_ID_TOKEN_REQUEST_TOKEN`
+ *      + `ACTIONS_ID_TOKEN_REQUEST_URL` are present, GET the token from
+ *      the request URL with the request token as bearer + `audience=sigstore`.
+ *   4. Interactive browser flow — only when stdout is a TTY. Prints a
+ *      sigstore-issuer URL, listens on `127.0.0.1:<rand>`, waits for the
+ *      OAuth redirect carrying the access_token. If we can't bind a
+ *      local port we fall back to asking the user to paste the token
+ *      manually.
+ *
+ * If none of the four work → throws with a clear error directing the
+ * operator at the available knobs.
+ *
+ * **Tests.** The resolver is fully dependency-injectable: the env-var
+ * shape, TTY-ness, and (for the GH Actions branch) the fetch function
+ * are passed in. Interactive flow has a short-circuit (`interactive: false`)
+ * the tests use to avoid spinning up a real OAuth listener.
+ */
+import { createServer } from 'node:http';
+import { randomBytes, createHash } from 'node:crypto';
+/**
+ * Sentinel error thrown when no OIDC source produces a usable token.
+ * Carries a `code` discriminant so callers can map back into a
+ * structured `PublishError`.
+ */
+export class OidcResolutionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'OidcResolutionError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Resolver
+// ---------------------------------------------------------------------------
+/** Default sigstore public-good issuer. Matches cosign's default. */
+const DEFAULT_ISSUER = 'https://oauth2.sigstore.dev/auth';
+/** Public OAuth client id for the sigstore public-good issuer. */
+const SIGSTORE_OAUTH_CLIENT_ID = 'sigstore';
+export async function resolveOidcToken(opts) {
+    // 1. --identity-token flag (highest precedence).
+    if (opts.identityTokenFlag && opts.identityTokenFlag.length > 0) {
+        return { token: opts.identityTokenFlag, source: 'flag' };
+    }
+    // 2. GGUI_OIDC_TOKEN env var.
+    const envToken = opts.env['GGUI_OIDC_TOKEN'];
+    if (typeof envToken === 'string' && envToken.length > 0) {
+        return { token: envToken, source: 'env' };
+    }
+    // 3. GitHub Actions ambient OIDC.
+    const ghRequestToken = opts.env['ACTIONS_ID_TOKEN_REQUEST_TOKEN'];
+    const ghRequestUrl = opts.env['ACTIONS_ID_TOKEN_REQUEST_URL'];
+    if (typeof ghRequestToken === 'string' &&
+        ghRequestToken.length > 0 &&
+        typeof ghRequestUrl === 'string' &&
+        ghRequestUrl.length > 0) {
+        const token = await fetchGitHubActionsToken({
+            requestToken: ghRequestToken,
+            requestUrl: ghRequestUrl,
+            fetchImpl: opts.fetch ?? globalThis.fetch.bind(globalThis),
+        });
+        return { token, source: 'github-actions' };
+    }
+    // 4. Interactive browser flow — TTY-gated.
+    if (opts.isTty && opts.interactive !== false) {
+        const token = await runInteractiveFlow({
+            issuer: opts.issuer ?? DEFAULT_ISSUER,
+            stdout: opts.stdout ?? ((s) => void process.stdout.write(s)),
+            prompt: opts.prompt,
+            openBrowser: opts.openBrowser,
+        });
+        return { token, source: 'interactive' };
+    }
+    throw new OidcResolutionError('no_token_available', 'no OIDC token available. Provide one of:\n' +
+        '  --identity-token <jwt>\n' +
+        '  GGUI_OIDC_TOKEN env var\n' +
+        '  ACTIONS_ID_TOKEN_REQUEST_TOKEN + ACTIONS_ID_TOKEN_REQUEST_URL (GitHub Actions)\n' +
+        '  run from a TTY for the interactive browser flow');
+}
+// ---------------------------------------------------------------------------
+// GitHub Actions ambient OIDC
+//
+// Standard pattern from the actions/toolkit docs:
+//   GET <ACTIONS_ID_TOKEN_REQUEST_URL>&audience=sigstore
+//   Authorization: bearer <ACTIONS_ID_TOKEN_REQUEST_TOKEN>
+//   → { value: "<jwt>" }
+// ---------------------------------------------------------------------------
+async function fetchGitHubActionsToken(opts) {
+    // Audience query parameter — sigstore's Fulcio expects `sigstore`.
+    const url = appendAudience(opts.requestUrl, 'sigstore');
+    let res;
+    try {
+        res = await opts.fetchImpl(url, {
+            method: 'GET',
+            headers: {
+                Authorization: `bearer ${opts.requestToken}`,
+                Accept: 'application/json; api-version=2.0',
+            },
+        });
+    }
+    catch (err) {
+        throw new OidcResolutionError('github_actions_fetch_failed', `GitHub Actions OIDC fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!res.ok) {
+        let body = '';
+        try {
+            body = await res.text();
+        }
+        catch {
+            // ignore
+        }
+        throw new OidcResolutionError('github_actions_fetch_failed', `GitHub Actions OIDC fetch returned HTTP ${res.status}${body ? `: ${body.slice(0, 200)}` : ''}`);
+    }
+    let parsed;
+    try {
+        parsed = await res.json();
+    }
+    catch (err) {
+        throw new OidcResolutionError('github_actions_fetch_failed', `GitHub Actions OIDC response was not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        typeof parsed.value !== 'string') {
+        throw new OidcResolutionError('github_actions_fetch_failed', 'GitHub Actions OIDC response missing `value` string');
+    }
+    const value = parsed.value;
+    if (value.length === 0) {
+        throw new OidcResolutionError('github_actions_fetch_failed', 'GitHub Actions OIDC `value` was empty');
+    }
+    return value;
+}
+/**
+ * Append `audience=<aud>` to a URL, handling whether one is already
+ * present. The Actions request URL ships with `?api-version=...` already.
+ */
+function appendAudience(url, audience) {
+    const sep = url.includes('?') ? '&' : '?';
+    return `${url}${sep}audience=${encodeURIComponent(audience)}`;
+}
+// ---------------------------------------------------------------------------
+// Interactive browser flow — PKCE OAuth against the sigstore public-good
+// issuer.
+//
+// Flow:
+//   1. Bind a local HTTP listener on 127.0.0.1:<random>.
+//   2. Build the issuer URL with redirect_uri = http://127.0.0.1:<port>/callback.
+//   3. Print the URL + (try to) open the user's browser. They sign in
+//      against the configured IdP (Google/Microsoft/GitHub via Dex).
+//   4. The issuer redirects back to our listener with `?code=...&state=...`.
+//   5. We exchange the code for an id_token via the issuer's /token endpoint.
+//
+// If binding the listener fails (sandboxed env, no localhost network),
+// fall back to the manual-paste path: print the URL with `redirect_uri=urn:ietf:wg:oauth:2.0:oob`
+// and prompt the operator to paste the token directly.
+// ---------------------------------------------------------------------------
+async function runInteractiveFlow(opts) {
+    let listener;
+    try {
+        listener = await startCallbackListener();
+    }
+    catch {
+        listener = undefined;
+    }
+    // PKCE pair — code_verifier kept locally, code_challenge sent to the
+    // issuer. The fallback (manual-paste) doesn't need them but generating
+    // them unconditionally keeps the two branches symmetrical.
+    const codeVerifier = base64UrlEncode(randomBytes(32));
+    const codeChallenge = base64UrlEncode(createHash('sha256').update(codeVerifier).digest());
+    const state = base64UrlEncode(randomBytes(16));
+    if (listener) {
+        const redirectUri = `http://127.0.0.1:${listener.port}/callback`;
+        const authUrl = buildAuthUrl({
+            issuer: opts.issuer,
+            redirectUri,
+            codeChallenge,
+            state,
+        });
+        opts.stdout(`\nOpen this URL in your browser to authenticate:\n  ${authUrl}\n\n`);
+        if (opts.openBrowser) {
+            try {
+                await opts.openBrowser(authUrl);
+            }
+            catch {
+                // ignore — printed URL is enough
+            }
+        }
+        let callback;
+        try {
+            callback = await listener.waitForCallback();
+        }
+        catch (err) {
+            throw new OidcResolutionError('interactive_failed', `interactive callback failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            listener.close();
+        }
+        if (callback.state !== state) {
+            throw new OidcResolutionError('interactive_failed', 'OAuth state mismatch — possible CSRF; aborting.');
+        }
+        return await exchangeCodeForToken({
+            issuer: opts.issuer,
+            code: callback.code,
+            codeVerifier,
+            redirectUri,
+        });
+    }
+    // Manual-paste fallback — couldn't bind a local port.
+    const oobRedirect = 'urn:ietf:wg:oauth:2.0:oob';
+    const authUrl = buildAuthUrl({
+        issuer: opts.issuer,
+        redirectUri: oobRedirect,
+        codeChallenge,
+        state,
+    });
+    opts.stdout(`\nUnable to bind a local OAuth listener.\n` +
+        `Open this URL in your browser, authenticate, and paste the resulting token below:\n  ${authUrl}\n\n`);
+    const promptFn = opts.prompt;
+    if (!promptFn) {
+        throw new OidcResolutionError('interactive_failed', 'interactive fallback requires an injected prompt function (or a free localhost port)');
+    }
+    const pasted = await promptFn('OIDC token: ');
+    if (!pasted || pasted.length === 0) {
+        throw new OidcResolutionError('interactive_failed', 'no token provided');
+    }
+    return pasted.trim();
+}
+function startCallbackListener() {
+    return new Promise((resolveStart, rejectStart) => {
+        let resolveCb;
+        let rejectCb;
+        const server = createServer((req, res) => {
+            if (!req.url) {
+                res.statusCode = 400;
+                res.end('missing url');
+                return;
+            }
+            const u = new URL(req.url, `http://127.0.0.1`);
+            const code = u.searchParams.get('code');
+            const state = u.searchParams.get('state');
+            const error = u.searchParams.get('error');
+            if (error) {
+                res.statusCode = 400;
+                res.end(`error: ${error}`);
+                rejectCb?.(new Error(`issuer returned error=${error}`));
+                return;
+            }
+            if (!code || !state) {
+                res.statusCode = 400;
+                res.end('missing code/state');
+                return;
+            }
+            res.statusCode = 200;
+            res.setHeader('Content-Type', 'text/html; charset=utf-8');
+            res.end('<html><body><p>Authentication complete. You can close this tab.</p></body></html>');
+            resolveCb?.({ code, state });
+        });
+        server.once('error', (err) => rejectStart(err));
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            if (!addr || typeof addr.port !== 'number') {
+                rejectStart(new Error('failed to bind callback listener'));
+                return;
+            }
+            const port = addr.port;
+            resolveStart({
+                port,
+                waitForCallback() {
+                    return new Promise((resolveInner, rejectInner) => {
+                        resolveCb = resolveInner;
+                        rejectCb = rejectInner;
+                    });
+                },
+                close() {
+                    server.close();
+                },
+            });
+        });
+    });
+}
+function buildAuthUrl(opts) {
+    const params = new URLSearchParams({
+        response_type: 'code',
+        client_id: SIGSTORE_OAUTH_CLIENT_ID,
+        scope: 'openid email',
+        redirect_uri: opts.redirectUri,
+        code_challenge: opts.codeChallenge,
+        code_challenge_method: 'S256',
+        state: opts.state,
+    });
+    return `${opts.issuer}/auth?${params.toString()}`;
+}
+async function exchangeCodeForToken(opts) {
+    const body = new URLSearchParams({
+        grant_type: 'authorization_code',
+        code: opts.code,
+        code_verifier: opts.codeVerifier,
+        client_id: SIGSTORE_OAUTH_CLIENT_ID,
+        redirect_uri: opts.redirectUri,
+    });
+    let res;
+    try {
+        res = await fetch(`${opts.issuer}/token`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: body.toString(),
+        });
+    }
+    catch (err) {
+        throw new OidcResolutionError('interactive_failed', `token exchange failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!res.ok) {
+        let text = '';
+        try {
+            text = await res.text();
+        }
+        catch {
+            // ignore
+        }
+        throw new OidcResolutionError('interactive_failed', `token exchange HTTP ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}`);
+    }
+    let parsed;
+    try {
+        parsed = await res.json();
+    }
+    catch (err) {
+        throw new OidcResolutionError('interactive_failed', `token exchange response was not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        typeof parsed.id_token !== 'string') {
+        throw new OidcResolutionError('interactive_failed', 'token exchange response missing `id_token` string');
+    }
+    return parsed.id_token;
+}
+function base64UrlEncode(buf) {
+    const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
+    return b.toString('base64').replace(/=+$/, '').replace(/\+/g, '-').replace(/\//g, '_');
+}

package/dist/internal/register-author-key.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Outcome discriminator. The `ok: false` `code` union surfaces specific
+ * HTTP failure modes so callers (notably a future `--json` flag) can
+ * branch on the registry's closed error set without parsing the human-
+ * readable message:
+ *
+ *   - `unauthorized`     ← HTTP 401 (missing/invalid Cognito JWT).
+ *   - `invalid_request`  ← HTTP 400 (malformed body or wrong key length).
+ *   - `key_conflict`     ← HTTP 409 (collision against an existing row).
+ *   - `http-error`       ← any other non-2xx (5xx or unexpected status).
+ *
+ * The body's `error` field on a structured error response is read first
+ * (it carries the registry's authoritative {@link RegisterAuthorKeyErrorCode});
+ * status-code mapping is the fallback when the body omits it. The
+ * human-readable `message` always flows through from the body when
+ * present.
+ */
+export type RegisterKeyOutcome = {
+    readonly ok: true;
+    readonly status: 200 | 201;
+    readonly registryUrl: string;
+    readonly subject: string;
+    readonly keyId: string;
+} | {
+    readonly ok: false;
+    readonly code: 'no-registry' | 'invalid-registry' | 'no-keypair' | 'auth_failed' | 'auth_config_missing' | 'network-error' | 'unauthorized' | 'invalid_request' | 'key_conflict' | 'http-error' | 'bad-response';
+    readonly message: string;
+};
+export interface RunRegisterKeyFlags {
+    readonly scope: string;
+    readonly registry?: string;
+}
+export interface RunRegisterKeyDeps {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly fetch: typeof fetch;
+    readonly now: () => number;
+}
+/**
+ * Run the register flow end-to-end. Never throws — every error path
+ * returns a structured outcome.
+ */
+export declare function runRegisterAuthorKey(flags: RunRegisterKeyFlags, deps: RunRegisterKeyDeps): Promise<RegisterKeyOutcome>;
+//# sourceMappingURL=register-author-key.d.ts.map

package/dist/internal/register-author-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-author-key.d.ts","sourceRoot":"","sources":["../../src/internal/register-author-key.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,IAAI,EACT,aAAa,GACb,kBAAkB,GAClB,YAAY,GACZ,aAAa,GACb,qBAAqB,GACrB,eAAe,GACf,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,YAAY,GACZ,cAAc,CAAC;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,mBAAmB,EAC1B,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,kBAAkB,CAAC,CA0J7B"}

package/dist/internal/register-author-key.js

@@ -0,0 +1,212 @@
+/**
+ * `ggui keys register`.
+ *
+ * Register a per-scope Ed25519 public key with the marketplace
+ * registry's `POST /author-keys` endpoint. Replaces the operator-owned
+ * `aws dynamodb put-item` workflow that previously required raw IAM
+ * credentials + registry table knowledge.
+ *
+ * The publisher's identity is the Cognito JWT's `sub` (server-side);
+ * the body carries only `publicKeyBase64`. `keyId` is derived from the
+ * public-key bytes on the server, so re-running with the same key is
+ * idempotent (200 OK).
+ *
+ * Auth + registry-URL resolution match the publish flow (so the
+ * cached token / `GGUI_REGISTRY` env / `ggui.json#registry` chain
+ * works the same way operators are used to).
+ */
+import { readFileSync } from 'node:fs';
+import { REGISTER_AUTHOR_KEY_ERROR_CODES } from '@ggui-ai/registry-core';
+import { acquireHostedAuthJwt, } from './artifact-publish.js';
+import { resolveRegistryUrl } from './artifact-search.js';
+import { getPublicKeyPath, hasKeypair } from './key-store.js';
+/**
+ * Run the register flow end-to-end. Never throws — every error path
+ * returns a structured outcome.
+ */
+export async function runRegisterAuthorKey(flags, deps) {
+    // 1. Registry URL — same resolver as publish/search.
+    const resolved = resolveRegistryUrl({
+        ...(flags.registry !== undefined ? { flag: flags.registry } : {}),
+        cwd: deps.cwd,
+        env: {
+            GGUI_REGISTRY: typeof deps.env['GGUI_REGISTRY'] === 'string' ? deps.env['GGUI_REGISTRY'] : undefined,
+        },
+    });
+    if ('error' in resolved) {
+        const isNoRegistry = resolved.error.startsWith('no registry');
+        return {
+            ok: false,
+            code: isNoRegistry ? 'no-registry' : 'invalid-registry',
+            message: resolved.error,
+        };
+    }
+    // 2. Read the local public key. Same per-scope keystore the publish
+    // flow auto-generates on first publish — operators run `ggui keys
+    // register` AFTER `ggui blueprint publish` / `ggui gadget publish`
+    // generates the keypair locally + the registry rejects with
+    // `unknown_key`.
+    if (!hasKeypair(flags.scope)) {
+        return {
+            ok: false,
+            code: 'no-keypair',
+            message: `no keypair found for scope ${flags.scope}. Run \`ggui blueprint publish\` or ` +
+                `\`ggui gadget publish\` under this scope first — the publish flow generates the ` +
+                `keypair on first run.`,
+        };
+    }
+    const pubPath = getPublicKeyPath(flags.scope);
+    let publicKeyBytes;
+    try {
+        publicKeyBytes = readFileSync(pubPath);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: 'no-keypair',
+            message: `failed to read public key at ${pubPath}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (publicKeyBytes.length !== 32) {
+        return {
+            ok: false,
+            code: 'no-keypair',
+            message: `public key at ${pubPath} is not a 32-byte Ed25519 key (got ${publicKeyBytes.length} bytes)`,
+        };
+    }
+    const publicKeyBase64 = publicKeyBytes.toString('base64');
+    // 3. Hosted-auth Cognito JWT — same chain as publish.
+    const auth = await acquireHostedAuthJwt({
+        registryUrl: resolved.url,
+        env: deps.env,
+        cwd: deps.cwd,
+        now: deps.now,
+    });
+    if (!auth.ok) {
+        return {
+            ok: false,
+            code: auth.error.code,
+            message: auth.error.message,
+        };
+    }
+    // 4. POST /author-keys
+    const url = `${resolved.url}/author-keys`;
+    let res;
+    try {
+        res = await deps.fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${auth.token.idToken}`,
+            },
+            body: JSON.stringify({ publicKeyBase64 }),
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: 'network-error',
+            message: `failed to reach registry at ${resolved.url}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        return {
+            ok: false,
+            code: 'bad-response',
+            message: `registry responded with HTTP ${res.status} but body was not valid JSON`,
+        };
+    }
+    if (res.status === 200 || res.status === 201) {
+        if (body === null || typeof body !== 'object') {
+            return {
+                ok: false,
+                code: 'bad-response',
+                message: `registry returned ${res.status} with malformed body`,
+            };
+        }
+        const okBody = body;
+        if (typeof okBody.subject !== 'string' || typeof okBody.keyId !== 'string') {
+            return {
+                ok: false,
+                code: 'bad-response',
+                message: `registry returned ${res.status} with missing subject/keyId fields`,
+            };
+        }
+        return {
+            ok: true,
+            status: res.status,
+            registryUrl: resolved.url,
+            subject: okBody.subject,
+            keyId: okBody.keyId,
+        };
+    }
+    // Defend against `null` / non-object JSON (e.g. `body === null` or
+    // `body === "string-literal"`) — accessing `.error`/`.message` on
+    // those would throw. Treat them like the "no structured body" case.
+    const errBody = body !== null && typeof body === 'object'
+        ? body
+        : {};
+    const errMsg = typeof errBody.message === 'string'
+        ? errBody.message
+        : `registry returned HTTP ${res.status}`;
+    // Prefer the body's `error` discriminator (closed enum from registry-
+    // core's `REGISTER_AUTHOR_KEY_ERROR_CODES`) over status-code mapping —
+    // the body is authoritative when present + well-formed. Status-code
+    // mapping is the fallback when the body omits `error`.
+    const bodyError = mapBodyErrorToCode(errBody.error);
+    if (bodyError !== undefined) {
+        return { ok: false, code: bodyError, message: errMsg };
+    }
+    return {
+        ok: false,
+        code: mapStatusToCode(res.status),
+        message: errMsg,
+    };
+}
+/**
+ * Map the registry's structured `error` discriminator to the CLI's
+ * outcome `code`. Returns `undefined` when the body doesn't carry a
+ * recognised code so the caller can fall back to status-code mapping.
+ * The `server_error` value from the registry deliberately maps to the
+ * CLI's generic `http-error` bucket — the CLI doesn't distinguish 500-
+ * shaped responses from other non-2xx statuses.
+ */
+function mapBodyErrorToCode(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    // Defend against a future registry-core enum addition leaking through
+    // — only map values the CLI knows about.
+    if (!REGISTER_AUTHOR_KEY_ERROR_CODES.includes(raw)) {
+        return undefined;
+    }
+    switch (raw) {
+        case 'unauthorized':
+            return 'unauthorized';
+        case 'invalid_request':
+            return 'invalid_request';
+        case 'key_conflict':
+            return 'key_conflict';
+        case 'server_error':
+            return 'http-error';
+        default:
+            return undefined;
+    }
+}
+/**
+ * Map an HTTP status to the CLI outcome `code` when the body didn't
+ * carry a structured `error` discriminator. Everything outside the
+ * three explicit buckets collapses to `http-error`.
+ */
+function mapStatusToCode(status) {
+    if (status === 401)
+        return 'unauthorized';
+    if (status === 400)
+        return 'invalid_request';
+    if (status === 409)
+        return 'key_conflict';
+    return 'http-error';
+}

package/dist/local-keys.d.ts

@@ -0,0 +1,47 @@
+interface LocalKeyRow {
+    pairingId: string;
+    deviceName: string;
+    createdAt: number;
+    lastUsedAt?: number;
+    lastRemoteAddress?: string;
+    token: string;
+}
+interface LocalKeysState {
+    v: 1;
+    pairings: LocalKeyRow[];
+    idCounter: number;
+}
+/**
+ * Read + parse the keys file, or return empty state when the file is
+ * missing / empty (first-boot path). Throws on malformed JSON or
+ * unsupported schema — loud failure beats silent overwrite.
+ */
+export declare function loadLocalKeys(path: string): LocalKeysState;
+/**
+ * Atomic write — temp file + rename, `0600` perms, parent dir created
+ * with `0700` if missing. Mirrors `InMemoryPairingService.persistToDisk`
+ * so the two writers can't disagree on file shape.
+ */
+export declare function saveLocalKeys(path: string, state: LocalKeysState): void;
+/**
+ * Mint a new `ggui_user_*` token and append it to `state`. Returns
+ * the appended row (caller surfaces the plaintext token to the
+ * operator — one-time reveal, exactly like cloud-side `keys create`).
+ */
+export declare function mintLocalKey(state: LocalKeysState, opts: {
+    readonly deviceName: string;
+    readonly now?: () => number;
+}): LocalKeyRow;
+/**
+ * Remove the row with `pairingId`. Idempotent — revoking a missing
+ * id is not an error. Returns `true` when a row was removed.
+ */
+export declare function revokeLocalKey(state: LocalKeysState, pairingId: string): boolean;
+/**
+ * Render a fixed-width table to stdout. Columns chosen to match the
+ * cloud-side `keys list` shape so operators recognize the layout
+ * regardless of which mode they're in.
+ */
+export declare function formatLocalKeyTable(state: LocalKeysState): string;
+export {};
+//# sourceMappingURL=local-keys.d.ts.map

package/dist/local-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-keys.d.ts","sourceRoot":"","sources":["../src/local-keys.ts"],"names":[],"mappings":"AA4BA,UAAU,WAAW;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,UAAU,cAAc;IACtB,CAAC,EAAE,CAAC,CAAC;IACL,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAe1D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI,CAqBvE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAE,GACjE,WAAW,CAYb;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAIhF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAkBjE"}