flipstream 0.4.0

package/dist/lib/output/redact.js

@@ -0,0 +1,47 @@
+const MASK = '***';
+// Object keys whose values are secrets, compared in a normalized form so
+// snake_case / camelCase / kebab-case and any casing all match.
+const SECRET_KEYS = new Set([
+    'accesstoken',
+    'authorization',
+    'clientsecret',
+    'code',
+    'codeverifier',
+    'idtoken',
+    // Admin/connection material (E7-0b): a connection's secret reference and its
+    // provider config blob — masked whole (their presence, not contents, is all an
+    // agent needs). secret_id/secretId/secret-id all normalize to 'secretid'.
+    'parameters',
+    'refreshtoken',
+    'secret',
+    'secretid',
+]);
+function normalizeKey(key) {
+    return key.toLowerCase().replaceAll(/[_-]/g, '');
+}
+// Secret query/form params (URLs and x-www-form-urlencoded bodies), preserving
+// structure: only the value is masked, other params (e.g. state) stay visible.
+// `code_verifier` precedes `code` so the longer name wins.
+const SECRET_PARAMS = /(^|[?&])(access_token|refresh_token|id_token|code_verifier|code|authorization|client_secret)=[^&\s]+/gi;
+// JWT-shaped tokens (three base64url segments) anywhere in free text, even with
+// no preceding key — masks tokens that leak into stack traces / messages.
+const JWT_SHAPE = /eyJ[\w-]*\.[\w-]+\.[\w-]+/g;
+function redactString(value) {
+    return value.replaceAll(SECRET_PARAMS, `$1$2=${MASK}`).replaceAll(JWT_SHAPE, MASK);
+}
+// Return a redacted deep copy of `value` (never mutates the input). Applied to
+// every log/debug/error path so tokens never reach stdout/stderr/logs.
+export function redact(value) {
+    if (typeof value === 'string')
+        return redactString(value);
+    if (Array.isArray(value))
+        return value.map((item) => redact(item));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, val] of Object.entries(value)) {
+            out[key] = SECRET_KEYS.has(normalizeKey(key)) ? MASK : redact(val);
+        }
+        return out;
+    }
+    return value;
+}

package/dist/lib/output/render.d.ts

@@ -0,0 +1,2 @@
+export { renderNdjson } from './ndjson.js';
+export declare function renderJson(value: unknown): void;

package/dist/lib/output/render.js

@@ -0,0 +1,8 @@
+export { renderNdjson } from './ndjson.js';
+// Write a single JSON document to stdout (pretty-printed, trailing newline).
+// stdout = data only; diagnostics/prompts go to stderr. NOTE: under oclif's
+// --json (enableJsonFlag) the run() return value is auto-serialized — use this
+// only when NOT relying on that path. BaseCommand.respond() handles the mode gate.
+export function renderJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}

package/dist/lib/output/table.d.ts

@@ -0,0 +1,3 @@
+import { type TableOptions } from '@oclif/table';
+export type TableColumns<T extends Record<string, unknown>> = TableOptions<T>['columns'];
+export declare function renderTable<T extends Record<string, unknown>>(data: T[], columns: TableColumns<T>, emptyMessage?: string): void;

package/dist/lib/output/table.js

@@ -0,0 +1,19 @@
+import { makeTable } from '@oclif/table';
+// Render a table to STDOUT — HUMAN output ONLY. Callers invoke this from a
+// respond/respondList human formatter, which never runs under --json/--ndjson, so
+// the agent contract (machine output is pure JSON/NDJSON) is preserved. Honors
+// NO_COLOR (strips ANSI) and the terminal width (truncates overflowing cells).
+export function renderTable(data, columns, emptyMessage = '(none)') {
+    if (data.length === 0) {
+        process.stdout.write(`${emptyMessage}\n`);
+        return;
+    }
+    const table = makeTable({
+        borderStyle: 'vertical-with-outline',
+        columns,
+        data,
+        noStyle: Boolean(process.env.NO_COLOR),
+        overflow: 'truncate-end',
+    });
+    process.stdout.write(`${table}\n`);
+}

package/dist/lib/store/credentials.d.ts

@@ -0,0 +1,12 @@
+export declare const SKEW_SECONDS = 60;
+export interface Credentials {
+    accessToken: string;
+    clientId: string;
+    expiresAt: number;
+    redirectUri: string;
+    refreshToken: string;
+    scopes: string[];
+}
+export declare function keyOf(host: string): string;
+export declare function freshAccessToken(creds: Credentials | null): null | string;
+export declare function parseCredentials(secret: string): Credentials | null;

package/dist/lib/store/credentials.js

@@ -0,0 +1,40 @@
+// Treat a token as stale this many seconds BEFORE its real expiry, to avoid
+// using a token that expires mid-request.
+export const SKEW_SECONDS = 60;
+// Per-host keychain account key (trailing slashes stripped so h and h/ collide).
+export function keyOf(host) {
+    return host.replace(/\/+$/, '');
+}
+function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+// The access token if present and not within SKEW_SECONDS of expiry, else null.
+export function freshAccessToken(creds) {
+    if (creds && creds.accessToken && creds.expiresAt - SKEW_SECONDS > nowSeconds()) {
+        return creds.accessToken;
+    }
+    return null;
+}
+// Parse a stored secret into Credentials; null on non-JSON or missing required fields.
+export function parseCredentials(secret) {
+    try {
+        const obj = JSON.parse(secret);
+        if (typeof obj.accessToken !== 'string' ||
+            typeof obj.refreshToken !== 'string' ||
+            typeof obj.expiresAt !== 'number' ||
+            typeof obj.clientId !== 'string') {
+            return null;
+        }
+        return {
+            accessToken: obj.accessToken,
+            clientId: obj.clientId,
+            expiresAt: obj.expiresAt,
+            redirectUri: typeof obj.redirectUri === 'string' ? obj.redirectUri : '',
+            refreshToken: obj.refreshToken,
+            scopes: Array.isArray(obj.scopes) ? obj.scopes : [],
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/store/index.d.ts

@@ -0,0 +1,5 @@
+import { type TokenStore } from './keyring.js';
+export * from './credentials.js';
+export { KeyringStore, type TokenStore } from './keyring.js';
+export { MemoryStore } from './memory-store.js';
+export declare function createStore(): TokenStore;

package/dist/lib/store/index.js

@@ -0,0 +1,21 @@
+import { KeyringStore } from './keyring.js';
+import { MemoryStore } from './memory-store.js';
+export * from './credentials.js';
+export { KeyringStore } from './keyring.js';
+export { MemoryStore } from './memory-store.js';
+// Keyed on a registered Symbol so the singleton is shared even when this module
+// is loaded as two instances in one process — which happens on Windows ESM (the
+// same file resolved via different path spellings) and would otherwise split the
+// in-memory store between a test and the in-process command it drives.
+const MEMORY_STORE = Symbol.for('io.flipstream.cli.memory-store');
+// Choose the token store. FLIPSTREAM_NO_KEYRING forces an in-memory store (no
+// keychain) — useful for headless/CI and tests; the process-global singleton
+// keeps state across calls (and across module instances) within a process.
+export function createStore() {
+    if (process.env.FLIPSTREAM_NO_KEYRING) {
+        const globals = globalThis;
+        globals[MEMORY_STORE] ??= new MemoryStore();
+        return globals[MEMORY_STORE];
+    }
+    return new KeyringStore();
+}

package/dist/lib/store/keyring.d.ts

@@ -0,0 +1,16 @@
+import { type Credentials } from './credentials.js';
+export declare const KEYRING_SERVICE = "io.flipstream.cli";
+export interface TokenStore {
+    accessTokenIfFresh(host: string): null | string;
+    available(): boolean;
+    clear(host: string): void;
+    load(host: string): Credentials | null;
+    save(host: string, creds: Credentials): void;
+}
+export declare class KeyringStore implements TokenStore {
+    accessTokenIfFresh(host: string): null | string;
+    available(): boolean;
+    clear(host: string): void;
+    load(host: string): Credentials | null;
+    save(host: string, creds: Credentials): void;
+}

package/dist/lib/store/keyring.js

@@ -0,0 +1,45 @@
+import { Entry } from '@napi-rs/keyring';
+import { freshAccessToken, keyOf, parseCredentials } from './credentials.js';
+// FROZEN. Tokens are stored in the OS keychain under this service id. Renaming
+// it strands users' tokens (silent logout + orphaned secrets), so any change
+// requires a one-time keyring-only migration (read old id -> write new id ->
+// delete old) — never a plaintext intermediary.
+export const KEYRING_SERVICE = 'io.flipstream.cli';
+// TokenStore backed by the OS keychain. The whole Credentials JSON is the single
+// secret per host (keyed by host).
+export class KeyringStore {
+    accessTokenIfFresh(host) {
+        return freshAccessToken(this.load(host));
+    }
+    available() {
+        try {
+            new Entry(KEYRING_SERVICE, '__probe__').getPassword();
+            return true;
+        }
+        catch (error) {
+            // "not found" means the keychain works but is empty (available); any other
+            // failure (e.g. no Secret Service on headless Linux) means it is unavailable.
+            return /not found|no (matching )?(entry|password|item)|could not be found/i.test(error.message);
+        }
+    }
+    clear(host) {
+        try {
+            new Entry(KEYRING_SERVICE, keyOf(host)).deletePassword();
+        }
+        catch {
+            // Nothing stored for this host.
+        }
+    }
+    load(host) {
+        try {
+            const secret = new Entry(KEYRING_SERVICE, keyOf(host)).getPassword();
+            return secret ? parseCredentials(secret) : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    save(host, creds) {
+        new Entry(KEYRING_SERVICE, keyOf(host)).setPassword(JSON.stringify(creds));
+    }
+}

package/dist/lib/store/memory-store.d.ts

@@ -0,0 +1,10 @@
+import type { TokenStore } from './keyring.js';
+import { type Credentials } from './credentials.js';
+export declare class MemoryStore implements TokenStore {
+    private readonly entries;
+    accessTokenIfFresh(host: string): null | string;
+    available(): boolean;
+    clear(host: string): void;
+    load(host: string): Credentials | null;
+    save(host: string, creds: Credentials): void;
+}

package/dist/lib/store/memory-store.js

@@ -0,0 +1,21 @@
+import { freshAccessToken, keyOf } from './credentials.js';
+// In-memory TokenStore for tests and headless/CI (no real keychain available).
+// Interchangeable with KeyringStore via the TokenStore interface.
+export class MemoryStore {
+    entries = new Map();
+    accessTokenIfFresh(host) {
+        return freshAccessToken(this.load(host));
+    }
+    available() {
+        return true;
+    }
+    clear(host) {
+        this.entries.delete(keyOf(host));
+    }
+    load(host) {
+        return this.entries.get(keyOf(host)) ?? null;
+    }
+    save(host, creds) {
+        this.entries.set(keyOf(host), creds);
+    }
+}