google-apis-cli 0.1.0 → 0.3.0

package/dist/src/credentials.js

@@ -0,0 +1,342 @@
+// Credentials: the only reader and writer of config.json and credentials.json (epic #30 D8, D13).
+// Settings precedence, Bearer vs API key, token refresh + persistence, loopback/manual login.
+import { hash, randomBytes } from 'node:crypto';
+import { chmod, readFile, rm } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { Writable } from 'node:stream';
+import { CodeChallengeMethod, OAuth2Client } from 'google-auth-library';
+import { shortScope, writeAtomic } from './catalog.js';
+import { codeOf, GapiError, messageOf } from './errors.js';
+import { isRecord } from './json.js';
+const LOOPBACK_HOST = '127.0.0.1';
+const LOOPBACK_PORT = 4600; // fixed port; vmCODE forwards it for headless use
+const REDIRECT_URI = `http://${LOOPBACK_HOST}:${LOOPBACK_PORT}`; // both login flows
+const IDENTITY_SCOPES = ['openid', 'email'];
+const RELOGIN = 'run gapi auth login';
+const NO_KEY = 'API key required; pass --api-key, set GAPI_API_KEY or run gapi auth setup';
+// `||`, not `??`: an empty GAPI_CONFIG_DIR must not resolve secrets into the cwd.
+export const configDir = (env) => env.GAPI_CONFIG_DIR || join(homedir(), '.config', 'gapi');
+const API_KEY_SETTING = { flag: 'api-key', env: 'GAPI_API_KEY', key: 'api_key' };
+// `gapi auth setup` asks the OAuth client, then each entry header, then the API key.
+const CLIENT_FIELDS = [
+    { key: 'oauth_client_id', label: 'OAuth client id', required: true, secret: false },
+    { key: 'oauth_client_secret', label: 'OAuth client secret', required: true, secret: true },
+];
+const API_KEY_FIELD = {
+    key: 'api_key',
+    label: 'API key (optional, CrUX/PageSpeed)',
+    required: false,
+    secret: true,
+};
+const isCredentials = (v) => isRecord(v) && typeof v.refresh_token === 'string';
+export function openCredentials({ dir, env, oauth = (opts) => new OAuth2Client(opts), warn = () => { }, stdin = process.stdin, stderr = process.stderr, }) {
+    const configFile = join(dir, 'config.json');
+    const credentialsFile = join(dir, 'credentials.json');
+    let apiKey;
+    let tokenClient;
+    let saving; // the refreshed-token write the 'tokens' event starts
+    const ask = (q, opts) => defaultPrompt(q, { ...opts, input: stdin, output: stderr });
+    // Only a missing file reads as {}: anything else stops before `setup` can overwrite it.
+    // The parse error is not echoed, since V8 quotes the file text (secrets) in it.
+    const readConfig = async () => {
+        let text;
+        try {
+            text = await readFile(configFile, 'utf8');
+        }
+        catch (e) {
+            if (codeOf(e) === 'ENOENT')
+                return {};
+            throw new GapiError(2, `cannot read ${configFile}: ${messageOf(e)}`);
+        }
+        let cfg;
+        try {
+            cfg = JSON.parse(text);
+        }
+        catch {
+            throw new GapiError(2, `${configFile} is not valid JSON; fix or remove it`);
+        }
+        if (!isRecord(cfg))
+            throw new GapiError(2, `${configFile} is not a JSON object; fix or remove it`);
+        return cfg;
+    };
+    // Owner-only: file 600 by temp file + rename, so a crash or a concurrent gapi never
+    // leaves a broken file. `mkdir` mode applies only on create: narrow an existing dir too.
+    const writeSecure = async (file, data) => {
+        await writeAtomic(file, JSON.stringify(data, null, 2));
+        await chmod(dir, 0o700);
+    };
+    const readCredentials = async () => {
+        let creds;
+        try {
+            creds = JSON.parse(await readFile(credentialsFile, 'utf8'));
+        }
+        catch {
+            // missing or unreadable reads as logged out, same as a bad shape below
+        }
+        if (!isCredentials(creds))
+            throw new GapiError(2, `not logged in; ${RELOGIN}`);
+        return creds;
+    };
+    const client = async (redirectUri) => {
+        const cfg = await readConfig();
+        const clientId = env.GAPI_OAUTH_CLIENT_ID || String(cfg.oauth_client_id ?? '');
+        const clientSecret = env.GAPI_OAUTH_CLIENT_SECRET || String(cfg.oauth_client_secret ?? '');
+        if (!clientId || !clientSecret) {
+            throw new GapiError(2, 'OAuth client not configured; run gapi auth setup');
+        }
+        return oauth({ clientId, clientSecret, redirectUri });
+    };
+    // Exchange a consent code (with its PKCE verifier) for tokens and persist them.
+    const exchange = async (c, code, codeVerifier) => {
+        const { tokens } = await c.getToken({ code, codeVerifier }).catch((e) => {
+            throw new GapiError(2, `token exchange failed: ${messageOf(e)}`);
+        });
+        // Google: "refresh tokens are always returned for installed applications".
+        if (!tokens.refresh_token)
+            throw new GapiError(2, `no refresh token returned; ${RELOGIN}`);
+        await writeSecure(credentialsFile, tokens);
+        return tokens;
+    };
+    // Precedence flag → env → config file; an empty env var falls through, as in `configDir`.
+    const setting = (flags, cfg, { flag, env: name, key }) => {
+        const v = flags[flag] ?? (env[name] || cfg[key]);
+        return v == null ? undefined : String(v);
+    };
+    async function settings(flags, headerSpecs = []) {
+        const cfg = await readConfig();
+        apiKey = setting(flags, cfg, API_KEY_SETTING);
+        const headers = {};
+        for (const { name, flag, env: envName, configKey } of headerSpecs) {
+            const v = setting(flags, cfg, { flag, env: envName, key: configKey });
+            if (v !== undefined)
+                headers[name] = v;
+        }
+        const project = setting(flags, cfg, {
+            flag: 'project',
+            env: 'GOOGLE_CLOUD_PROJECT',
+            key: 'project',
+        });
+        return { project, headers };
+    }
+    const authorize = async (auth, { redact = false } = {}) => {
+        if (auth.kind === 'apiKey') {
+            // D8: a method that lists no scope needs the key; one with only never-set scopes may omit it.
+            if (apiKey === undefined) {
+                if (auth.scopes.length > 0)
+                    return {};
+                if (!redact)
+                    throw new GapiError(2, NO_KEY);
+                warn(NO_KEY);
+            }
+            return { 'X-Goog-Api-Key': redact ? '<redacted>' : String(apiKey) };
+        }
+        if (redact)
+            return { Authorization: 'Bearer <redacted>' };
+        if (!tokenClient) {
+            const c = await client();
+            c.setCredentials(await readCredentials());
+            // An event listener is not awaited: keep the write so the refresh below can await it.
+            // Copy now: google-auth-library puts the old refresh token back on this object.
+            c.on('tokens', (t) => {
+                const fresh = { ...t };
+                saving = readCredentials().then((stored) => writeSecure(credentialsFile, { ...stored, ...fresh }));
+            });
+            tokenClient = c;
+        }
+        const { token } = await tokenClient.getAccessToken().catch((e) => {
+            const data = isRecord(e) && isRecord(e.response) ? e.response.data : undefined;
+            const reason = isRecord(data) ? data.error : undefined;
+            if (reason === 'invalid_grant')
+                throw new GapiError(2, `token expired or revoked; ${RELOGIN}`);
+            throw new GapiError(2, `token refresh failed: ${messageOf(e)}; ${RELOGIN}`);
+        });
+        const saved = saving;
+        saving = undefined;
+        await saved?.catch((e) => {
+            throw new GapiError(2, `cannot save the refreshed token: ${messageOf(e)}`);
+        });
+        if (!token)
+            throw new GapiError(2, `no access token; ${RELOGIN}`);
+        return { Authorization: `Bearer ${token}` };
+    };
+    // Response cache key part (ADR 0001): one per Google account, never the token itself.
+    // No stored token → undefined; entries are stored only after an authorized success.
+    async function identity(auth) {
+        if (auth.kind === 'apiKey')
+            return 'apiKey';
+        const token = (await readCredentials().catch(() => undefined))?.refresh_token;
+        return token ? hash('sha256', token) : undefined;
+    }
+    // Both flows send `state` and a PKCE S256 challenge, and redeem one redirect URL.
+    async function login({ consent, manual = false, prompt = ask, }) {
+        const c = await client(REDIRECT_URI);
+        const state = randomBytes(32).toString('base64url');
+        const { codeVerifier, codeChallenge } = await c.generateCodeVerifierAsync();
+        const url = c.generateAuthUrl({
+            access_type: 'offline',
+            prompt: 'consent',
+            scope: [...consent, ...IDENTITY_SCOPES],
+            state,
+            code_challenge_method: CodeChallengeMethod.S256,
+            code_challenge: codeChallenge,
+        });
+        // `state` first, so only Google's own redirect can end the login (CSRF).
+        const redeem = async (redirect) => {
+            const query = redirect.searchParams;
+            if (query.get('state') !== state)
+                throw new GapiError(2, 'state mismatch');
+            const error = query.get('error');
+            if (error)
+                throw new GapiError(2, `consent failed: ${error}`);
+            const code = query.get('code');
+            if (!code)
+                throw new GapiError(2, 'no code in redirect');
+            const tokens = await exchange(c, code, codeVerifier);
+            // Google: "Your app must verify which scopes were actually granted".
+            const granted = new Set((tokens.scope ?? '').split(' '));
+            const missing = consent.filter((s) => !granted.has(s)).map(shortScope);
+            if (missing.length > 0)
+                warn(`scopes not granted: ${missing.join(', ')}`);
+            return tokens;
+        };
+        if (manual) {
+            stderr.write(`Open this URL and grant access:\n${url}\n` +
+                `After consent the browser cannot load ${LOOPBACK_HOST}:${LOOPBACK_PORT}; ` +
+                'paste the full URL from its address bar.\n');
+            const redirect = URL.parse((await prompt('redirected URL: ')).trim());
+            if (!redirect)
+                throw new GapiError(2, 'not a URL; paste the full URL from the address bar');
+            return redeem(redirect);
+        }
+        return new Promise((resolve, reject) => {
+            const server = createServer(async (req, res) => {
+                const redirect = new URL(req.url ?? '/', REDIRECT_URI);
+                if (redirect.pathname !== '/') {
+                    res.statusCode = 404; // e.g. /favicon.ico: keep waiting for the redirect
+                    res.end();
+                    return;
+                }
+                if (redirect.searchParams.get('state') !== state) {
+                    res.statusCode = 400; // not Google's redirect: keep waiting for it
+                    res.end('gapi: state mismatch');
+                    return;
+                }
+                try {
+                    const tokens = await redeem(redirect);
+                    res.end('gapi: authorized. You can close this tab.');
+                    resolve(tokens);
+                }
+                catch (e) {
+                    res.statusCode = 400;
+                    res.end(`gapi: ${messageOf(e)}`);
+                    reject(e);
+                }
+                finally {
+                    server.close();
+                }
+            });
+            server.on('error', (e) => reject(new GapiError(2, `cannot listen on ${LOOPBACK_HOST}:${LOOPBACK_PORT}: ${e.message}`)));
+            server.listen(LOOPBACK_PORT, LOOPBACK_HOST, () => {
+                const { address, port } = server.address();
+                stderr.write(`Listening on ${address}:${port}\nOpen this URL and grant access:\n${url}\n`);
+            });
+        });
+    }
+    async function status(consent) {
+        const cfg = await readConfig();
+        const creds = await readCredentials();
+        const granted = new Set((creds.scope ?? '').split(' ').filter(Boolean));
+        return {
+            account: creds.id_token ? accountFromIdToken(creds.id_token) : null,
+            hasRefreshToken: Boolean(creds.refresh_token),
+            hasApiKey: setting({}, cfg, API_KEY_SETTING) !== undefined,
+            expiryDate: creds.expiry_date ? new Date(creds.expiry_date).toISOString() : null,
+            scopes: [...granted].map(shortScope),
+            missing: consent.filter((s) => !granted.has(s)).map(shortScope),
+        };
+    }
+    // Revoke, then delete (the `gcloud auth revoke` pattern, #151). Revoking the refresh
+    // token ends the whole grant. Google answers 400 `invalid_token` for a token already
+    // invalid or revoked; another 400 error code is a failed request.
+    // Any other failure keeps credentials.json, so the logout can be retried.
+    // No stored token (missing or unreadable file) leaves nothing to revoke. The revoke
+    // endpoint takes only the token, so no OAuth client id or secret is needed.
+    async function logout() {
+        const token = (await readCredentials().catch(() => undefined))?.refresh_token;
+        if (token) {
+            await oauth()
+                .revokeToken(token)
+                .catch((e) => {
+                const data = isRecord(e) && isRecord(e.response) ? e.response.data : undefined;
+                if (!isRecord(data) || data.error !== 'invalid_token')
+                    throw new GapiError(1, `token revoke failed, credentials kept: ${messageOf(e)}`);
+                warn('refresh token already invalid or revoked');
+            });
+        }
+        await rm(credentialsFile, { force: true });
+    }
+    // `headers`: every entry's header specs, tagged with the entry's api.
+    async function setup(headers, prompt = ask) {
+        const cfg = await readConfig();
+        const fields = [
+            ...CLIENT_FIELDS,
+            ...headers.map((h) => ({
+                key: h.configKey,
+                label: `${h.api} ${h.configKey} (optional)`,
+                required: false,
+                secret: false,
+            })),
+            API_KEY_FIELD,
+        ];
+        for (const { key, label, required, secret } of fields) {
+            const cur = cfg[key];
+            const hint = cur != null ? ' [keep current]' : required ? '' : ' (blank to skip)';
+            const v = (await prompt(`${label}${hint}: `, { secret })).trim();
+            if (v)
+                cfg[key] = v;
+            else if (required && cur == null)
+                throw new GapiError(3, `${label} is required`);
+        }
+        await writeSecure(configFile, cfg);
+        return configFile;
+    }
+    return { settings, authorize, identity, login, status, logout, setup };
+}
+// Decode a JWT payload without verifying (display only; it is our own token).
+function accountFromIdToken(idToken) {
+    try {
+        const payload = JSON.parse(Buffer.from(idToken.split('.')[1], 'base64url').toString());
+        if (!isRecord(payload))
+            return null;
+        const account = payload.email || payload.sub;
+        return typeof account === 'string' ? account : null;
+    }
+    catch {
+        return null;
+    }
+}
+// `secret: true` keeps the typed value off the screen. Node has no masking
+// option, so point readline's echo at a sink and print the question ourselves.
+// `terminal: true` is what makes this safe: it puts the tty in raw mode, so the
+// driver stops echoing too and the sink is the only writer left. Streams are
+// injected (Credentials passes the ones `run` got), so the masking has a test.
+export async function defaultPrompt(q, { secret = false, input, output, terminal, }) {
+    if (secret)
+        output.write(q);
+    const rl = createInterface({
+        input,
+        output: secret ? new Writable({ write: (_c, _e, cb) => cb() }) : output,
+        terminal: secret ? true : terminal,
+    });
+    try {
+        return await rl.question(secret ? '' : q);
+    }
+    finally {
+        rl.close();
+        if (secret)
+            output.write('\n'); // the swallowed Enter never printed one
+    }
+}

package/dist/src/errors.js

@@ -0,0 +1,16 @@
+export class GapiError extends Error {
+    exit;
+    body;
+    constructor(exit, message, body) {
+        super(message);
+        this.name = 'GapiError';
+        this.exit = exit;
+        this.body = body;
+    }
+}
+// A caught value's message: an Error's own text (no `Error: ` prefix), anything else as a string.
+export const messageOf = (e) => (e instanceof Error ? e.message : String(e));
+// A Node system error's `code` (`ENOENT`, `EACCES`, …); undefined for anything else.
+export const codeOf = (e) => e instanceof Error && 'code' in e ? e.code : undefined;
+// Why a file operation failed: the system error code when there is one, else the message.
+export const reasonOf = (e) => String(codeOf(e) ?? messageOf(e));

package/dist/src/json.js

@@ -0,0 +1,11 @@
+// Guards for parsed JSON: narrow `unknown` with `isRecord` + `typeof`, never a cast.
+export const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// JSON text parsed; text that is not JSON (an HTML error page, a proxy reply) stays as is.
+export function parseOrText(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}