@apostra/sdk 0.38.0 → 0.39.0

package/README.md

@@ -26,8 +26,11 @@ values. Use `accessToken` for an existing REST/M2M bearer token, or
 one credential source. `m2mTokenProvider` acquires and caches a server-side
 client-credentials token with the published M2M endpoint; it refreshes 60
 seconds before expiry and shares a concurrent refresh. Never put API keys or
-client secrets in browser bundles, URLs, examples or logs. The package does not
-persist credentials or replay 401 responses. M2M token refreshes have a
+client secrets in browser bundles, URLs, examples or logs. With no
+explicit credential and no `APOSTRA_API_KEY`, a Node.js client uses the login
+that `apostra login` stored for the base URL, if there is one; the SDK never
+opens a browser and writes only to that login's file (refreshed tokens). The
+package does not replay 401 responses. M2M token refreshes have a
 30-second deadline by default; pass `timeoutMs` to override it.
 
 ```ts

package/SKILL.md

@@ -5,7 +5,7 @@ description: Choose the Apostra TypeScript SDK method for a coding task, then re
 
 # Apostra TypeScript SDK
 
-Read the [SDK guide](https://docs.apostra.com/v2/sdk), [V3 HTTP API
+Read the [SDK guide](https://docs.apostra.com/v3/sdk-guide), [V3 HTTP API
 guide](https://docs.apostra.com/v3/http-api), and [authentication
 guide](https://docs.apostra.com/v3/authentication) before relying on an
 operation. They are the source of truth for inputs, results, permissions, and

package/dist/cli-login.d.ts

@@ -0,0 +1,76 @@
+import type { TokenProvider } from './transport.js';
+export type CliLoginEntry = {
+    issuer: string;
+    resource: string;
+    clientId: string;
+    accessToken: string;
+    refreshToken: string;
+    /** ISO-8601 time the access token stops working. */
+    expiresAt: string;
+    accountId: string;
+    scopes: string[];
+};
+export type CliLoginDiscovery = {
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    revocationEndpoint?: string;
+    codeChallengeMethods?: string[];
+};
+export type CliLoginTokens = Pick<CliLoginEntry, 'accessToken' | 'refreshToken' | 'expiresAt'> & {
+    scopes?: string[];
+    accountId?: string;
+};
+type Fetch = typeof globalThis.fetch;
+type Options = {
+    fetch?: Fetch;
+};
+/** `${XDG_CONFIG_HOME:-~/.config}/apostra/credentials.json` (`%APPDATA%` on Windows). */
+export declare function credentialsPath(): string;
+/** The store key: the API base URL without a trailing slash. */
+export declare function normalizeBaseUrl(raw: string): string;
+/** The first-party public client for an API origin. */
+export declare const cliClientId: (resource: string) => string;
+export declare function readCliLogin(baseUrl: string): CliLoginEntry | undefined;
+/** Like `readCliLogin`, but never throws: for the SDK's default credential chain. */
+export declare function storedCliLogin(baseUrl: string): CliLoginEntry | undefined;
+export declare const isFresh: (entry: Pick<CliLoginEntry, "expiresAt">) => boolean;
+/**
+ * Serialise every read-modify-write of the store, across processes. Refresh
+ * tokens rotate, so two processes must never present the same one outside the
+ * server's reuse grace. A lock older than 30 seconds belongs to a dead process.
+ */
+export declare function withCliLoginLock<T>(fn: () => Promise<T>): Promise<T>;
+/** Save a login. Call inside `withCliLoginLock`. */
+export declare function writeCliLogin(baseUrl: string, entry: CliLoginEntry): void;
+/** Protected-resource metadata, then authorization-server metadata (RFC 9728, RFC 8414). */
+export declare function discoverCliLogin(resource: string, { fetch: f }?: Options): Promise<CliLoginDiscovery>;
+export declare function exchangeCliLoginCode(options: Options, discovery: CliLoginDiscovery, resource: string, grant: {
+    code: string;
+    verifier: string;
+    redirectUri: string;
+}): Promise<CliLoginTokens>;
+/**
+ * Return a usable login for `baseUrl`, refreshing it if the access token is
+ * about to expire. After taking the lock the file is read again: if another
+ * process refreshed first, its token is used and no request is made.
+ */
+export declare function refreshCliLogin(baseUrl: string, options?: Options): Promise<CliLoginEntry>;
+/**
+ * Revoke the refresh token (RFC 7009), then delete the entry. The entry is
+ * deleted even when revocation fails; `revoked` tells the caller which.
+ */
+export declare function logoutCliLogin(baseUrl: string, { fetch: f }?: Options): Promise<{
+    found: boolean;
+    revoked: boolean;
+}>;
+/**
+ * A token provider backed by `apostra login`. Use it as `tokenProvider`, or
+ * rely on the default credential chain, which uses it when no explicit
+ * credential or `APOSTRA_API_KEY` is set and a login exists for the base URL.
+ */
+export declare function cliLoginTokenProvider(options?: {
+    baseUrl?: string;
+    fetch?: Fetch;
+}): TokenProvider;
+export {};

package/dist/cli-login.js

@@ -0,0 +1,377 @@
+/**
+ * The credential store behind `apostra login`, shared by the CLI and the SDK.
+ *
+ * Node only. Nothing here imports a Node module at load time (it uses
+ * `process.getBuiltinModule`), so a browser bundle can include the SDK and
+ * simply never call it. The SDK never opens a browser; the interactive sign-in
+ * lives in `@apostra/cli`.
+ */
+import { baseUrl as defaultBaseUrl } from './generated/metadata.js';
+const FRESH_MARGIN_MS = 60_000;
+const REQUEST_TIMEOUT_MS = 15_000;
+const LOCK_STALE_MS = 30_000;
+const LOCK_HEARTBEAT_MS = 5_000;
+const LOCK_WAIT_MS = 30_000;
+function proc() {
+    const p = globalThis.process;
+    if (!p?.versions?.node || typeof p.getBuiltinModule !== 'function')
+        throw new Error('Apostra CLI login is available only in Node.js');
+    return p;
+}
+function node() {
+    const p = proc();
+    const get = p.getBuiltinModule;
+    return {
+        fs: get('node:fs'),
+        os: get('node:os'),
+        path: get('node:path'),
+    };
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const errorCode = (error) => isRecord(error) && typeof error.code === 'string' ? error.code : undefined;
+/** `${XDG_CONFIG_HOME:-~/.config}/apostra/credentials.json` (`%APPDATA%` on Windows). */
+export function credentialsPath() {
+    const { os, path } = node();
+    const { env, platform } = proc();
+    const base = platform === 'win32'
+        ? (env.APPDATA ?? path.join(os.homedir(), 'AppData', 'Roaming'))
+        : env.XDG_CONFIG_HOME && path.isAbsolute(env.XDG_CONFIG_HOME)
+            ? env.XDG_CONFIG_HOME
+            : path.join(os.homedir(), '.config');
+    return path.join(base, 'apostra', 'credentials.json');
+}
+function secureUrl(value, name) {
+    const url = new URL(typeof value === 'string' ? value : '');
+    if (url.username ||
+        url.password ||
+        url.hash ||
+        (url.protocol !== 'https:' &&
+            !(url.protocol === 'http:' &&
+                ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))))
+        throw new TypeError(`${name} must be an HTTPS URL (HTTP only on loopback)`);
+    return url.href;
+}
+/** The store key: the API base URL without a trailing slash. */
+export function normalizeBaseUrl(raw) {
+    const url = new URL(secureUrl(raw, 'Base URL'));
+    if (url.search)
+        throw new TypeError('Base URL must not have a query string');
+    return url.href.replace(/\/$/, '');
+}
+/** The first-party public client for an API origin. */
+export const cliClientId = (resource) => `${new URL(resource).origin}/oauth/clients/apostra-cli.json`;
+function parseEntry(value) {
+    if (!isRecord(value))
+        return undefined;
+    const text = ['issuer', 'resource', 'clientId', 'accessToken', 'refreshToken'];
+    if (!text.every((k) => typeof value[k] === 'string' && value[k]) ||
+        typeof value.expiresAt !== 'string' ||
+        Number.isNaN(Date.parse(value.expiresAt)) ||
+        typeof value.accountId !== 'string' ||
+        !Array.isArray(value.scopes) ||
+        !value.scopes.every((s) => typeof s === 'string'))
+        return undefined;
+    return value;
+}
+function readAll() {
+    const { fs } = node();
+    try {
+        const file = JSON.parse(fs.readFileSync(credentialsPath(), 'utf8'));
+        return isRecord(file) && isRecord(file.logins) ? file.logins : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Atomic (temp file + rename), directory 0700, file 0600. */
+function writeAll(logins) {
+    const { fs, path } = node();
+    const file = credentialsPath();
+    const dir = path.dirname(file);
+    if (Object.keys(logins).length === 0) {
+        fs.rmSync(file, { force: true });
+        return;
+    }
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.chmodSync(dir, 0o700);
+    const temp = `${file}.${proc().pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    const fd = fs.openSync(temp, 'wx', 0o600);
+    try {
+        fs.writeSync(fd, `${JSON.stringify({ version: 1, logins }, null, 2)}\n`);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(temp, file);
+}
+export function readCliLogin(baseUrl) {
+    return parseEntry(readAll()[normalizeBaseUrl(baseUrl)]);
+}
+/** Like `readCliLogin`, but never throws: for the SDK's default credential chain. */
+export function storedCliLogin(baseUrl) {
+    try {
+        return readCliLogin(baseUrl);
+    }
+    catch {
+        return undefined;
+    }
+}
+export const isFresh = (entry) => Date.parse(entry.expiresAt) - FRESH_MARGIN_MS > Date.now();
+/**
+ * Serialise every read-modify-write of the store, across processes. Refresh
+ * tokens rotate, so two processes must never present the same one outside the
+ * server's reuse grace. A lock older than 30 seconds belongs to a dead process.
+ */
+export async function withCliLoginLock(fn) {
+    const { fs, path } = node();
+    const lock = `${credentialsPath()}.lock`;
+    fs.mkdirSync(path.dirname(lock), { recursive: true, mode: 0o700 });
+    // The lock file holds its owner's token, so a process only ever removes a
+    // lock it owns, and a heartbeat keeps a live lock fresh however long the
+    // bounded refresh takes. Only a lock whose heartbeat stopped is stale.
+    const owner = `${proc().pid}:${globalThis.crypto.randomUUID()}`;
+    const ownerOf = () => {
+        try {
+            return fs.readFileSync(lock, 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            const fd = fs.openSync(lock, 'wx', 0o600);
+            try {
+                fs.writeSync(fd, owner);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            break;
+        }
+        catch (error) {
+            if (errorCode(error) !== 'EEXIST')
+                throw error;
+            try {
+                const stale = ownerOf();
+                if (Date.now() - fs.statSync(lock).mtimeMs > LOCK_STALE_MS) {
+                    if (ownerOf() === stale)
+                        fs.rmSync(lock, { force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new Error('Timed out waiting for another Apostra login process');
+            await new Promise((r) => setTimeout(r, 25 + Math.random() * 50));
+        }
+    }
+    const heartbeat = setInterval(() => {
+        try {
+            if (ownerOf() === owner)
+                fs.utimesSync(lock, new Date(), new Date());
+        }
+        catch {
+            // A missed beat only shortens the lease; the owner check still holds.
+        }
+    }, LOCK_HEARTBEAT_MS);
+    heartbeat.unref?.();
+    try {
+        return await fn();
+    }
+    finally {
+        clearInterval(heartbeat);
+        if (ownerOf() === owner)
+            fs.rmSync(lock, { force: true });
+    }
+}
+/** Save a login. Call inside `withCliLoginLock`. */
+export function writeCliLogin(baseUrl, entry) {
+    writeAll({ ...readAll(), [normalizeBaseUrl(baseUrl)]: entry });
+}
+async function send(fetcher, url, init = {}) {
+    return fetcher(url, {
+        ...init,
+        headers: { Accept: 'application/json', ...init.headers },
+        redirect: 'error',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+}
+async function getJson(fetcher, url) {
+    const response = await send(fetcher, url);
+    if (!response.ok)
+        throw new Error(`Could not read ${url} (HTTP ${response.status})`);
+    return response.json();
+}
+function wellKnown(name, location) {
+    const url = new URL(location);
+    return `${url.origin}/.well-known/${name}${url.pathname === '/' ? '' : url.pathname}`;
+}
+/** Protected-resource metadata, then authorization-server metadata (RFC 9728, RFC 8414). */
+export async function discoverCliLogin(resource, { fetch: f = globalThis.fetch } = {}) {
+    const prm = await getJson(f, wellKnown('oauth-protected-resource', resource));
+    if (!isRecord(prm) ||
+        typeof prm.resource !== 'string' ||
+        prm.resource.replace(/\/$/, '') !== resource ||
+        !Array.isArray(prm.authorization_servers))
+        throw new Error(`${resource} does not publish OAuth protected-resource metadata`);
+    const issuer = secureUrl(prm.authorization_servers[0], 'Issuer').replace(/\/$/, '');
+    const as = await getJson(f, wellKnown('oauth-authorization-server', issuer));
+    if (!isRecord(as) || as.issuer !== issuer)
+        throw new Error(`${issuer} published mismatched authorization-server metadata`);
+    const methods = as.code_challenge_methods_supported;
+    return {
+        issuer,
+        authorizationEndpoint: secureUrl(as.authorization_endpoint, 'authorization_endpoint'),
+        tokenEndpoint: secureUrl(as.token_endpoint, 'token_endpoint'),
+        revocationEndpoint: as.revocation_endpoint === undefined
+            ? undefined
+            : secureUrl(as.revocation_endpoint, 'revocation_endpoint'),
+        codeChallengeMethods: Array.isArray(methods)
+            ? methods.map(String)
+            : undefined,
+    };
+}
+async function tokenRequest({ fetch: f = globalThis.fetch }, discovery, resource, form) {
+    const response = await send(f, discovery.tokenEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ ...form, resource }),
+    });
+    const body = await response.json().catch(() => undefined);
+    if (!response.ok) {
+        // Never echo the response body: it may carry reflected credentials.
+        if (isRecord(body) && body.error === 'invalid_grant')
+            throw new Error('Your Apostra login expired or was revoked. Run `apostra login` again.');
+        throw new Error(`Apostra token request failed (HTTP ${response.status})`);
+    }
+    if (!isRecord(body) ||
+        typeof body.access_token !== 'string' ||
+        !body.access_token ||
+        typeof body.expires_in !== 'number' ||
+        !(body.expires_in > 0))
+        throw new Error('Apostra token response is invalid');
+    // Rotation: the old refresh token is spent; keep the new one. A refresh that
+    // does not rotate keeps the old one, but a login with no refresh token
+    // could not be kept past the access token's hour, so it is refused here,
+    // before anything is written.
+    const refreshToken = typeof body.refresh_token === 'string' && body.refresh_token
+        ? body.refresh_token
+        : form.refresh_token;
+    if (!refreshToken)
+        throw new Error('Apostra did not return a refresh token, so this login cannot be kept. Run `apostra login` again.');
+    const account = body.account_id;
+    return {
+        accessToken: body.access_token,
+        refreshToken,
+        expiresAt: new Date(Date.now() + body.expires_in * 1000).toISOString(),
+        scopes: typeof body.scope === 'string'
+            ? body.scope.split(' ').filter(Boolean)
+            : undefined,
+        accountId: typeof account === 'string' || typeof account === 'number'
+            ? String(account)
+            : undefined,
+    };
+}
+export function exchangeCliLoginCode(options, discovery, resource, grant) {
+    return tokenRequest(options, discovery, resource, {
+        grant_type: 'authorization_code',
+        code: grant.code,
+        code_verifier: grant.verifier,
+        redirect_uri: grant.redirectUri,
+        client_id: cliClientId(resource),
+    });
+}
+/**
+ * Return a usable login for `baseUrl`, refreshing it if the access token is
+ * about to expire. After taking the lock the file is read again: if another
+ * process refreshed first, its token is used and no request is made.
+ */
+export async function refreshCliLogin(baseUrl, options = {}) {
+    const key = normalizeBaseUrl(baseUrl);
+    const missing = () => new Error(`Not signed in to ${key}. Run \`apostra login\`.`);
+    const first = readCliLogin(key);
+    if (!first)
+        throw missing();
+    if (isFresh(first))
+        return first;
+    return withCliLoginLock(async () => {
+        const entry = readCliLogin(key);
+        if (!entry)
+            throw missing();
+        if (isFresh(entry))
+            return entry;
+        const discovery = await discoverCliLogin(entry.resource, options);
+        const tokens = await tokenRequest(options, discovery, entry.resource, {
+            grant_type: 'refresh_token',
+            refresh_token: entry.refreshToken,
+            client_id: entry.clientId,
+        });
+        const next = {
+            ...entry,
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresAt: tokens.expiresAt,
+            scopes: tokens.scopes ?? entry.scopes,
+        };
+        writeCliLogin(key, next);
+        return next;
+    });
+}
+/**
+ * Revoke the refresh token (RFC 7009), then delete the entry. The entry is
+ * deleted even when revocation fails; `revoked` tells the caller which.
+ */
+export async function logoutCliLogin(baseUrl, { fetch: f = globalThis.fetch } = {}) {
+    const key = normalizeBaseUrl(baseUrl);
+    return withCliLoginLock(async () => {
+        const entry = readCliLogin(key);
+        if (!entry)
+            return { found: false, revoked: false };
+        let revoked = false;
+        try {
+            const { revocationEndpoint } = await discoverCliLogin(entry.resource, {
+                fetch: f,
+            });
+            if (revocationEndpoint)
+                revoked = (await send(f, revocationEndpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                    body: new URLSearchParams({
+                        token: entry.refreshToken,
+                        token_type_hint: 'refresh_token',
+                        client_id: entry.clientId,
+                    }),
+                })).ok;
+        }
+        catch {
+            revoked = false;
+        }
+        const { [key]: _removed, ...rest } = readAll();
+        writeAll(rest);
+        return { found: true, revoked };
+    });
+}
+/**
+ * A token provider backed by `apostra login`. Use it as `tokenProvider`, or
+ * rely on the default credential chain, which uses it when no explicit
+ * credential or `APOSTRA_API_KEY` is set and a login exists for the base URL.
+ */
+export function cliLoginTokenProvider(options = {}) {
+    const key = normalizeBaseUrl(options.baseUrl ?? proc().env.APOSTRA_BASE_URL ?? defaultBaseUrl);
+    let refreshing;
+    return () => {
+        const entry = readCliLogin(key);
+        if (entry && isFresh(entry))
+            return entry.accessToken;
+        refreshing ??= refreshCliLogin(key, { fetch: options.fetch })
+            .then((e) => e.accessToken)
+            .finally(() => {
+            refreshing = undefined;
+        });
+        return refreshing;
+    };
+}