@knowzai/core 0.1.0

package/dist/config.js

@@ -0,0 +1,178 @@
+/**
+ * Config system: `~/.knowz/config.json` with multi-profile support, Zod
+ * validation, and the resolution precedence flag > env > profile > default.
+ * Secrets are NEVER stored here (credential store owns those — N3).
+ *
+ * For test isolation set `KNOWZ_CONFIG_DIR` to redirect the config directory.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { z } from 'zod';
+import { KnowzError, ExitCode } from './errors.js';
+// ---------------------------------------------------------------------------
+// Built-in environment defaults
+// ---------------------------------------------------------------------------
+export const BUILTIN_API_URLS = {
+    dev: 'https://api.dev.knowz.io',
+    prod: 'https://api.knowz.io',
+};
+export const DEFAULT_PROFILE = 'dev';
+export const DEFAULT_API_URL = BUILTIN_API_URLS[DEFAULT_PROFILE];
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+export const ProfileConfigSchema = z
+    .object({
+    apiUrl: z.string().url(),
+    defaultVaultId: z.string().optional(),
+    email: z.string().optional(),
+    tenantId: z.string().optional(),
+    label: z.string().optional(),
+    /** When set, local storage uses this Postgres+pgvector DSN (see `knowz pg up`). */
+    pgDsn: z.string().optional(),
+})
+    .strict();
+/** Global (not per-profile) UI preferences. */
+export const UiConfigSchema = z
+    .object({
+    /** Interactive frontend: 'menu' (inquirer) or 'tui' (Ink, when available). */
+    frontend: z.enum(['menu', 'tui']).optional(),
+})
+    .strict();
+/**
+ * Portable platform provider presets. Kept in lockstep with the CLI's
+ * `PLATFORM_PROVIDERS` (deploy/portable/runtime-contract.json). Duplicated here
+ * because `@knowzai/core` is a leaf package the CLI depends on — it cannot import
+ * the CLI's platform-runtime module.
+ */
+export const PLATFORM_PROVIDER_PRESETS = ['offline', 'azure', 'gcp', 'knowz-cloud', 'openai-compatible'];
+/** Global (not per-profile) portable-platform deployment preferences. */
+export const PlatformConfigSchema = z
+    .object({
+    /** Provider preset reused on the next `knowz up` (never a secret). */
+    defaultProvider: z.enum(PLATFORM_PROVIDER_PRESETS).optional(),
+})
+    .strict();
+export const KnowzConfigSchema = z
+    .object({
+    activeProfile: z.string().min(1),
+    profiles: z.record(z.string(), ProfileConfigSchema),
+    /** Global UI preferences (optional; absent in existing configs). */
+    ui: UiConfigSchema.optional(),
+    /** Global portable-platform preferences (optional; absent in existing configs). */
+    platform: PlatformConfigSchema.optional(),
+})
+    .strict();
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+export function configDir() {
+    return process.env.KNOWZ_CONFIG_DIR ?? join(homedir(), '.knowz');
+}
+export function configPath() {
+    return join(configDir(), 'config.json');
+}
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+export function defaultConfig() {
+    return {
+        activeProfile: DEFAULT_PROFILE,
+        profiles: {
+            dev: { apiUrl: BUILTIN_API_URLS.dev },
+            prod: { apiUrl: BUILTIN_API_URLS.prod },
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Load / Save
+// ---------------------------------------------------------------------------
+/** Read + validate config. Missing file → built-in defaults. Invalid → KnowzError(Usage). */
+export function loadConfig() {
+    const path = configPath();
+    if (!existsSync(path))
+        return defaultConfig();
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        throw new KnowzError(`Unable to read config at ${path}`, ExitCode.Usage, { cause: e });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new KnowzError(`Config at ${path} is not valid JSON`, ExitCode.Usage, { cause: e });
+    }
+    const result = KnowzConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const first = result.error.issues[0];
+        const where = first ? `'${first.path.join('.') || '(root)'}': ${first.message}` : 'unknown';
+        throw new KnowzError(`Invalid config at ${path} — ${where}`, ExitCode.Usage);
+    }
+    return result.data;
+}
+/** Atomic write with file mode 0600 / dir mode 0700. */
+export function saveConfig(cfg) {
+    const validated = KnowzConfigSchema.parse(cfg);
+    const dir = configDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = configPath();
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(validated, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+}
+// ---------------------------------------------------------------------------
+// Resolution (flag > env > profile > default)
+// ---------------------------------------------------------------------------
+export function resolveProfileName(opts = {}, cfg) {
+    return opts.profileFlag ?? process.env.KNOWZ_PROFILE ?? cfg?.activeProfile ?? DEFAULT_PROFILE;
+}
+export function resolveProfile(opts = {}, cfg = loadConfig()) {
+    const name = resolveProfileName(opts, cfg);
+    const profile = cfg.profiles[name] ??
+        { apiUrl: BUILTIN_API_URLS[name] ?? DEFAULT_API_URL };
+    return { name, profile };
+}
+export function resolveApiUrl(opts = {}, cfg = loadConfig()) {
+    if (opts.apiUrlFlag)
+        return opts.apiUrlFlag;
+    if (process.env.KNOWZ_API_URL)
+        return process.env.KNOWZ_API_URL;
+    const { profile } = resolveProfile({ profileFlag: opts.profileFlag }, cfg);
+    return profile.apiUrl ?? DEFAULT_API_URL;
+}
+// ---------------------------------------------------------------------------
+// UI preferences (global, not per-profile)
+// ---------------------------------------------------------------------------
+/** The configured interactive frontend ('menu' | 'tui'), or undefined. */
+export function getUiFrontend(cfg) {
+    return cfg.ui?.frontend;
+}
+/** Set the interactive frontend preference. Throws on an unknown value. */
+export function setUiFrontend(cfg, frontend) {
+    const f = frontend.toLowerCase();
+    if (f !== 'menu' && f !== 'tui') {
+        throw new KnowzError(`Unknown UI frontend '${frontend}' (use 'menu' or 'tui').`, ExitCode.Usage);
+    }
+    cfg.ui = { ...(cfg.ui ?? {}), frontend: f };
+}
+// ---------------------------------------------------------------------------
+// Portable-platform preferences (global, not per-profile)
+// ---------------------------------------------------------------------------
+/** The persisted default portable-platform provider preset, or undefined. */
+export function getPlatformDefaultProvider(cfg) {
+    return cfg.platform?.defaultProvider;
+}
+/** Persist the default provider preset for future `knowz up` reruns. Throws on an unknown preset. */
+export function setPlatformDefaultProvider(cfg, provider) {
+    const p = provider.toLowerCase();
+    if (!PLATFORM_PROVIDER_PRESETS.includes(p)) {
+        throw new KnowzError(`Unknown platform provider '${provider}' (use ${PLATFORM_PROVIDER_PRESETS.join(', ')}).`, ExitCode.Usage);
+    }
+    cfg.platform = { ...(cfg.platform ?? {}), defaultProvider: p };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEnD,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E,MAAM,CAAC,MAAM,gBAAgB,GAA2B;IACtD,GAAG,EAAE,0BAA0B;IAC/B,IAAI,EAAE,sBAAsB;CAC7B,CAAC;AACF,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AACrC,MAAM,CAAC,MAAM,eAAe,GAAG,gBAAgB,CAAC,eAAe,CAAE,CAAC;AAElE,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KACjC,MAAM,CAAC;IACN,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACxB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACrC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,mFAAmF;IACnF,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,+CAA+C;AAC/C,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,MAAM,CAAC;IACN,8EAA8E;IAC9E,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC7C,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,mBAAmB,CAAU,CAAC;AAGlH,yEAAyE;AACzE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,CAAC;IACN,sEAAsE;IACtE,eAAe,EAAE,CAAC,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC,QAAQ,EAAE;CAC9D,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,MAAM,CAAC;IACN,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAChC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,mBAAmB,CAAC;IACnD,oEAAoE;IACpE,EAAE,EAAE,cAAc,CAAC,QAAQ,EAAE;IAC7B,mFAAmF;IACnF,QAAQ,EAAE,oBAAoB,CAAC,QAAQ,EAAE;CAC1C,CAAC;KACD,MAAM,EAAE,CAAC;AAOZ,8EAA8E;AAC9E,QAAQ;AACR,8EAA8E;AAE9E,MAAM,UAAU,SAAS;IACvB,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC;AACnE,CAAC;AACD,MAAM,UAAU,UAAU;IACxB,OAAO,IAAI,CAAC,SAAS,EAAE,EAAE,aAAa,CAAC,CAAC;AAC1C,CAAC;AAED,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,MAAM,UAAU,aAAa;IAC3B,OAAO;QACL,aAAa,EAAE,eAAe;QAC9B,QAAQ,EAAE;YACR,GAAG,EAAE,EAAE,MAAM,EAAE,gBAAgB,CAAC,GAAI,EAAE;YACtC,IAAI,EAAE,EAAE,MAAM,EAAE,gBAAgB,CAAC,IAAK,EAAE;SACzC;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E,6FAA6F;AAC7F,MAAM,UAAU,UAAU;IACxB,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;IAC1B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,aAAa,EAAE,CAAC;IAE9C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,UAAU,CAAC,4BAA4B,IAAI,EAAE,EAAE,QAAQ,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IACzF,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,UAAU,CAAC,aAAa,IAAI,oBAAoB,EAAE,QAAQ,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5F,MAAM,IAAI,UAAU,CAAC,qBAAqB,IAAI,MAAM,KAAK,EAAE,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,UAAU,CAAC,GAAgB;IACzC,MAAM,SAAS,GAAG,iBAAiB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;IACxB,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;IAC1B,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;IACzC,aAAa,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/E,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AACxB,CAAC;AAED,8EAA8E;AAC9E,8CAA8C;AAC9C,8EAA8E;AAE9E,MAAM,UAAU,kBAAkB,CAAC,OAAiC,EAAE,EAAE,GAAiB;IACvF,OAAO,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,GAAG,EAAE,aAAa,IAAI,eAAe,CAAC;AAChG,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,OAAiC,EAAE,EACnC,MAAmB,UAAU,EAAE;IAE/B,MAAM,IAAI,GAAG,kBAAkB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3C,MAAM,OAAO,GACX,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;QACjB,EAAE,MAAM,EAAE,gBAAgB,CAAC,IAAI,CAAC,IAAI,eAAe,EAA2B,CAAC;IAClF,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,OAAsD,EAAE,EACxD,MAAmB,UAAU,EAAE;IAE/B,IAAI,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC,UAAU,CAAC;IAC5C,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IAChE,MAAM,EAAE,OAAO,EAAE,GAAG,cAAc,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC;IAC3E,OAAO,OAAO,CAAC,MAAM,IAAI,eAAe,CAAC;AAC3C,CAAC;AAED,8EAA8E;AAC9E,2CAA2C;AAC3C,8EAA8E;AAE9E,0EAA0E;AAC1E,MAAM,UAAU,aAAa,CAAC,GAAgB;IAC5C,OAAO,GAAG,CAAC,EAAE,EAAE,QAAQ,CAAC;AAC1B,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,aAAa,CAAC,GAAgB,EAAE,QAAgB;IAC9D,MAAM,CAAC,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IACjC,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;QAChC,MAAM,IAAI,UAAU,CAAC,wBAAwB,QAAQ,0BAA0B,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;IACnG,CAAC;IACD,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED,8EAA8E;AAC9E,0DAA0D;AAC1D,8EAA8E;AAE9E,6EAA6E;AAC7E,MAAM,UAAU,0BAA0B,CAAC,GAAgB;IACzD,OAAO,GAAG,CAAC,QAAQ,EAAE,eAAe,CAAC;AACvC,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,0BAA0B,CAAC,GAAgB,EAAE,QAAgB;IAC3E,MAAM,CAAC,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IACjC,IAAI,CAAE,yBAA+C,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,UAAU,CAClB,8BAA8B,QAAQ,UAAU,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EACxF,QAAQ,CAAC,KAAK,CACf,CAAC;IACJ,CAAC;IACD,GAAG,CAAC,QAAQ,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,eAAe,EAAE,CAA2B,EAAE,CAAC;AAC3F,CAAC"}

package/dist/credential-store.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Credential store: OS keychain (preferred) with a mandatory AES-256-GCM
+ * encrypted-file fallback for headless/CI environments (Discovery D1 — keyring
+ * throws AccessDenied with no Secret Service). Secrets are NEVER plaintext.
+ *
+ * Security requirements S-N3-1..3:
+ *  - file perms 0600, dir 0700
+ *  - 96-bit random GCM nonce per write, auth tag verified on read (tamper -> throw)
+ *  - wrapping key derived via scrypt (N=2^15) from a passphrase, else a
+ *    machine-bound key. Machine-bound mode is OBFUSCATION, not protection.
+ *
+ * NOTE (deviation from S-N3-2): the KDF is Node's built-in scrypt rather than
+ * Argon2id — chosen to avoid an extra native dependency. scrypt is memory-hard
+ * and FIPS-adjacent; flagged for security re-review at Gate #3.
+ */
+export type KeyBackend = 'keychain' | 'encrypted-file';
+export type FileKeyMode = 'passphrase' | 'machine-bound';
+export interface CredentialStore {
+    backend(): KeyBackend;
+    fileKeyMode(): FileKeyMode | null;
+    setSecret(profile: string, secret: string): Promise<void>;
+    getSecret(profile: string): Promise<string | undefined>;
+    deleteSecret(profile: string): Promise<void>;
+    deleteAll(): Promise<void>;
+    listProfiles(): Promise<string[]>;
+}
+export interface OpenStoreOptions {
+    passphrase?: string;
+    /** Force the encrypted-file backend (skip keychain probe) — used in tests. */
+    forceFile?: boolean;
+}
+/** Probe the OS keychain; fall back to the encrypted file when unavailable. */
+export declare function openCredentialStore(opts?: OpenStoreOptions): Promise<CredentialStore>;
+//# sourceMappingURL=credential-store.d.ts.map

package/dist/credential-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-store.d.ts","sourceRoot":"","sources":["../src/credential-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAgBH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,gBAAgB,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,eAAe,CAAC;AAEzD,MAAM,WAAW,eAAe;IAC9B,OAAO,IAAI,UAAU,CAAC;IACtB,WAAW,IAAI,WAAW,GAAG,IAAI,CAAC;IAClC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACxD,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,YAAY,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACnC;AAuMD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,+EAA+E;AAC/E,wBAAsB,mBAAmB,CAAC,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,CAqB/F"}

package/dist/credential-store.js

@@ -0,0 +1,224 @@
+/**
+ * Credential store: OS keychain (preferred) with a mandatory AES-256-GCM
+ * encrypted-file fallback for headless/CI environments (Discovery D1 — keyring
+ * throws AccessDenied with no Secret Service). Secrets are NEVER plaintext.
+ *
+ * Security requirements S-N3-1..3:
+ *  - file perms 0600, dir 0700
+ *  - 96-bit random GCM nonce per write, auth tag verified on read (tamper -> throw)
+ *  - wrapping key derived via scrypt (N=2^15) from a passphrase, else a
+ *    machine-bound key. Machine-bound mode is OBFUSCATION, not protection.
+ *
+ * NOTE (deviation from S-N3-2): the KDF is Node's built-in scrypt rather than
+ * Argon2id — chosen to avoid an extra native dependency. scrypt is memory-hard
+ * and FIPS-adjacent; flagged for security re-review at Gate #3.
+ */
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, rmSync, } from 'node:fs';
+import { randomBytes, createCipheriv, createDecipheriv, scryptSync } from 'node:crypto';
+import { configDir } from './config.js';
+import { KnowzError, ExitCode } from './errors.js';
+const SERVICE = 'knowz-cli';
+const SCRYPT = { N: 1 << 15, r: 8, p: 1, maxmem: 96 * 1024 * 1024 };
+const encFile = () => join(configDir(), 'credentials.enc');
+const indexFile = () => join(configDir(), 'credential-index.json');
+const installSaltFile = () => join(configDir(), '.install-salt');
+function ensureDir() {
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+}
+function writeFile0600(path, data) {
+    ensureDir();
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, data, { mode: 0o600 });
+    renameSync(tmp, path);
+}
+// --------------------------------------------------------------------------
+// Profile index (so keychain — which can't enumerate — supports deleteAll/list)
+// --------------------------------------------------------------------------
+function readIndex() {
+    if (!existsSync(indexFile()))
+        return [];
+    try {
+        const v = JSON.parse(readFileSync(indexFile(), 'utf8'));
+        return Array.isArray(v) ? v.filter((x) => typeof x === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+function writeIndex(profiles) {
+    writeFile0600(indexFile(), JSON.stringify([...new Set(profiles)]));
+}
+function addToIndex(p) {
+    writeIndex([...readIndex(), p]);
+}
+function removeFromIndex(p) {
+    writeIndex(readIndex().filter((x) => x !== p));
+}
+function installSalt() {
+    if (existsSync(installSaltFile()))
+        return Buffer.from(readFileSync(installSaltFile(), 'utf8'), 'base64');
+    const salt = randomBytes(32);
+    writeFile0600(installSaltFile(), salt.toString('base64'));
+    return salt;
+}
+function deriveKey(mode, salt, passphrase) {
+    if (mode === 'passphrase') {
+        if (!passphrase)
+            throw new KnowzError('Passphrase required to unlock credentials', ExitCode.Auth);
+        return scryptSync(passphrase, salt, 32, SCRYPT);
+    }
+    // machine-bound: key material = installSalt + hostname, salted by `salt`.
+    const material = Buffer.concat([installSalt(), Buffer.from(hostname())]);
+    return scryptSync(material, salt, 32, SCRYPT);
+}
+class FileStore {
+    mode;
+    passphrase;
+    constructor(mode, passphrase) {
+        this.mode = mode;
+        this.passphrase = passphrase;
+    }
+    backend() {
+        return 'encrypted-file';
+    }
+    fileKeyMode() {
+        return this.mode;
+    }
+    loadMap() {
+        if (!existsSync(encFile()))
+            return {};
+        const env = JSON.parse(readFileSync(encFile(), 'utf8'));
+        const salt = Buffer.from(env.salt, 'base64');
+        const key = deriveKey(env.mode, salt, this.passphrase);
+        const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(env.nonce, 'base64'));
+        decipher.setAuthTag(Buffer.from(env.tag, 'base64'));
+        let plain;
+        try {
+            plain = Buffer.concat([decipher.update(Buffer.from(env.ct, 'base64')), decipher.final()]);
+        }
+        catch (e) {
+            throw new KnowzError('Credential file failed integrity check (wrong passphrase or tampering)', ExitCode.Auth, { cause: e });
+        }
+        return JSON.parse(plain.toString('utf8'));
+    }
+    saveMap(map) {
+        // Reuse the existing salt when the mode matches; else mint a new one.
+        let salt = randomBytes(16);
+        if (existsSync(encFile())) {
+            try {
+                const prev = JSON.parse(readFileSync(encFile(), 'utf8'));
+                if (prev.mode === this.mode)
+                    salt = Buffer.from(prev.salt, 'base64');
+            }
+            catch {
+                /* fall through with fresh salt */
+            }
+        }
+        const key = deriveKey(this.mode, salt, this.passphrase);
+        const nonce = randomBytes(12);
+        const cipher = createCipheriv('aes-256-gcm', key, nonce);
+        const ct = Buffer.concat([cipher.update(JSON.stringify(map), 'utf8'), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        const env = {
+            v: 1,
+            mode: this.mode,
+            salt: salt.toString('base64'),
+            nonce: nonce.toString('base64'),
+            ct: ct.toString('base64'),
+            tag: tag.toString('base64'),
+        };
+        writeFile0600(encFile(), JSON.stringify(env));
+    }
+    async setSecret(profile, secret) {
+        const map = this.loadMap();
+        map[profile] = secret;
+        this.saveMap(map);
+        addToIndex(profile);
+    }
+    async getSecret(profile) {
+        return this.loadMap()[profile];
+    }
+    async deleteSecret(profile) {
+        const map = this.loadMap();
+        delete map[profile];
+        this.saveMap(map);
+        removeFromIndex(profile);
+    }
+    async deleteAll() {
+        rmSync(encFile(), { force: true });
+        writeIndex([]);
+    }
+    async listProfiles() {
+        return Object.keys(this.loadMap());
+    }
+}
+// --------------------------------------------------------------------------
+// Keychain backend
+// --------------------------------------------------------------------------
+class KeychainStore {
+    Entry;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(Entry) {
+        this.Entry = Entry;
+    }
+    backend() {
+        return 'keychain';
+    }
+    fileKeyMode() {
+        return null;
+    }
+    async setSecret(profile, secret) {
+        new this.Entry(SERVICE, profile).setPassword(secret);
+        addToIndex(profile);
+    }
+    async getSecret(profile) {
+        try {
+            return new this.Entry(SERVICE, profile).getPassword() ?? undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async deleteSecret(profile) {
+        try {
+            new this.Entry(SERVICE, profile).deletePassword();
+        }
+        catch {
+            /* already absent */
+        }
+        removeFromIndex(profile);
+    }
+    async deleteAll() {
+        for (const p of readIndex())
+            await this.deleteSecret(p);
+        writeIndex([]);
+    }
+    async listProfiles() {
+        return readIndex();
+    }
+}
+/** Probe the OS keychain; fall back to the encrypted file when unavailable. */
+export async function openCredentialStore(opts = {}) {
+    const passphrase = opts.passphrase ?? process.env.KNOWZ_KEYRING_PASSPHRASE;
+    if (!opts.forceFile && process.env.KNOWZ_FORCE_FILE_KEYSTORE !== '1') {
+        try {
+            const mod = (await import('@napi-rs/keyring'));
+            const Entry = mod.Entry;
+            // Probe an actual write/read/delete; throws AccessDenied in headless envs.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const probe = new Entry(SERVICE, '__probe__');
+            probe.setPassword('1');
+            probe.getPassword();
+            probe.deletePassword();
+            return new KeychainStore(Entry);
+        }
+        catch {
+            /* fall through to encrypted file */
+        }
+    }
+    const mode = passphrase ? 'passphrase' : 'machine-bound';
+    return new FileStore(mode, passphrase);
+}
+//# sourceMappingURL=credential-store.js.map

package/dist/credential-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-store.js","sourceRoot":"","sources":["../src/credential-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACL,UAAU,EACV,SAAS,EACT,YAAY,EACZ,aAAa,EACb,UAAU,EACV,MAAM,GACP,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAenD,MAAM,OAAO,GAAG,WAAW,CAAC;AAC5B,MAAM,MAAM,GAAG,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAW,CAAC;AAE7E,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,iBAAiB,CAAC,CAAC;AAC3D,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,uBAAuB,CAAC,CAAC;AACnE,MAAM,eAAe,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,eAAe,CAAC,CAAC;AAEjE,SAAS,SAAS;IAChB,SAAS,CAAC,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAC3D,CAAC;AACD,SAAS,aAAa,CAAC,IAAY,EAAE,IAAY;IAC/C,SAAS,EAAE,CAAC;IACZ,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;IACzC,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1C,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AACxB,CAAC;AAED,6EAA6E;AAC7E,gFAAgF;AAChF,6EAA6E;AAE7E,SAAS,SAAS;IAChB,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;QAAE,OAAO,EAAE,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;QACxD,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AACD,SAAS,UAAU,CAAC,QAAkB;IACpC,aAAa,CAAC,SAAS,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACrE,CAAC;AACD,SAAS,UAAU,CAAC,CAAS;IAC3B,UAAU,CAAC,CAAC,GAAG,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;AAClC,CAAC;AACD,SAAS,eAAe,CAAC,CAAS;IAChC,UAAU,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAeD,SAAS,WAAW;IAClB,IAAI,UAAU,CAAC,eAAe,EAAE,CAAC;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,eAAe,EAAE,EAAE,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC;IACzG,MAAM,IAAI,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAC7B,aAAa,CAAC,eAAe,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,SAAS,CAAC,IAAiB,EAAE,IAAY,EAAE,UAAmB;IACrE,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;QAC1B,IAAI,CAAC,UAAU;YAAE,MAAM,IAAI,UAAU,CAAC,2CAA2C,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;QAClG,OAAO,UAAU,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;IAClD,CAAC;IACD,0EAA0E;IAC1E,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;IACzE,OAAO,UAAU,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,SAAS;IACgB;IAAoC;IAAjE,YAA6B,IAAiB,EAAmB,UAAmB;QAAvD,SAAI,GAAJ,IAAI,CAAa;QAAmB,eAAU,GAAV,UAAU,CAAS;IAAG,CAAC;IAExF,OAAO;QACL,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IACD,WAAW;QACT,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAEO,OAAO;QACb,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;YAAE,OAAO,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,CAAgB,CAAC;QACvE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC7C,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACvD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,aAAa,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;QACxF,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;QACpD,IAAI,KAAa,CAAC;QAClB,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC5F,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,UAAU,CAClB,wEAAwE,EACxE,QAAQ,CAAC,IAAI,EACb,EAAE,KAAK,EAAE,CAAC,EAAE,CACb,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAA2B,CAAC;IACtE,CAAC;IAEO,OAAO,CAAC,GAA2B;QACzC,sEAAsE;QACtE,IAAI,IAAI,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QAC3B,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,CAAgB,CAAC;gBACxE,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI;oBAAE,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YACvE,CAAC;YAAC,MAAM,CAAC;gBACP,kCAAkC;YACpC,CAAC;QACH,CAAC;QACD,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAG,cAAc,CAAC,aAAa,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QACzD,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACvF,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;QAChC,MAAM,GAAG,GAAgB;YACvB,CAAC,EAAE,CAAC;YACJ,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAC7B,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAC/B,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC;YACzB,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;SAC5B,CAAC;QACF,aAAa,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,OAAe,EAAE,MAAc;QAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC3B,GAAG,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAClB,UAAU,CAAC,OAAO,CAAC,CAAC;IACtB,CAAC;IACD,KAAK,CAAC,SAAS,CAAC,OAAe;QAC7B,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IACD,KAAK,CAAC,YAAY,CAAC,OAAe;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC3B,OAAO,GAAG,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAClB,eAAe,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IACD,KAAK,CAAC,SAAS;QACb,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACnC,UAAU,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IACD,KAAK,CAAC,YAAY;QAChB,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IACrC,CAAC;CACF;AAED,6EAA6E;AAC7E,mBAAmB;AACnB,6EAA6E;AAE7E,MAAM,aAAa;IAEY;IAD7B,8DAA8D;IAC9D,YAA6B,KAAU;QAAV,UAAK,GAAL,KAAK,CAAK;IAAG,CAAC;IAE3C,OAAO;QACL,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,WAAW;QACT,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,CAAC,SAAS,CAAC,OAAe,EAAE,MAAc;QAC7C,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACrD,UAAU,CAAC,OAAO,CAAC,CAAC;IACtB,CAAC;IACD,KAAK,CAAC,SAAS,CAAC,OAAe;QAC7B,IAAI,CAAC;YACH,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,WAAW,EAAE,IAAI,SAAS,CAAC;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IACD,KAAK,CAAC,YAAY,CAAC,OAAe;QAChC,IAAI,CAAC;YACH,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,cAAc,EAAE,CAAC;QACpD,CAAC;QAAC,MAAM,CAAC;YACP,oBAAoB;QACtB,CAAC;QACD,eAAe,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IACD,KAAK,CAAC,SAAS;QACb,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE;YAAE,MAAM,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACxD,UAAU,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IACD,KAAK,CAAC,YAAY;QAChB,OAAO,SAAS,EAAE,CAAC;IACrB,CAAC;CACF;AAYD,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAyB,EAAE;IACnE,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC;IAE3E,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,yBAAyB,KAAK,GAAG,EAAE,CAAC;QACrE,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAuB,CAAC;YACrE,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;YACxB,2EAA2E;YAC3E,8DAA8D;YAC9D,MAAM,KAAK,GAAG,IAAK,KAAa,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YACvD,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;YACvB,KAAK,CAAC,WAAW,EAAE,CAAC;YACpB,KAAK,CAAC,cAAc,EAAE,CAAC;YACvB,OAAO,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,oCAAoC;QACtC,CAAC;IACH,CAAC;IAED,MAAM,IAAI,GAAgB,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,eAAe,CAAC;IACtE,OAAO,IAAI,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AACzC,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+/** Stable process exit-code contract (see FEAT_KnowzCliFoundation). */
+export declare const ExitCode: {
+    readonly Success: 0;
+    readonly Generic: 1;
+    readonly Usage: 2;
+    readonly Auth: 3;
+    readonly Api: 4;
+    readonly NotFound: 5;
+};
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];
+/**
+ * A CLI error carrying the process exit code to use. The CLI's BaseCommand
+ * catch handler maps `exitCode` straight to `process.exitCode`; an unknown
+ * thrown Error maps to `ExitCode.Generic`.
+ */
+export declare class KnowzError extends Error {
+    readonly exitCode: ExitCodeValue;
+    constructor(message: string, exitCode?: ExitCodeValue, options?: {
+        cause?: unknown;
+    });
+}
+export declare function isKnowzError(e: unknown): e is KnowzError;
+/**
+ * Map any thrown value to a process exit code:
+ *  - KnowzError → its declared exitCode
+ *  - ApiError   → 404 NotFound(5), 401/403 Auth(3), else Api(4)
+ *  - anything else → Generic(1)
+ */
+export declare function exitCodeForError(e: unknown): ExitCodeValue;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,eAAO,MAAM,QAAQ;;;;;;;CAOX,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC;AAErE;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;gBAErB,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,aAAgC,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAMvG;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,UAAU,CAExD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,aAAa,CAQ1D"}

package/dist/errors.js

@@ -0,0 +1,53 @@
+/** Stable process exit-code contract (see FEAT_KnowzCliFoundation). */
+export const ExitCode = {
+    Success: 0,
+    Generic: 1,
+    Usage: 2,
+    Auth: 3,
+    Api: 4,
+    NotFound: 5,
+};
+/**
+ * A CLI error carrying the process exit code to use. The CLI's BaseCommand
+ * catch handler maps `exitCode` straight to `process.exitCode`; an unknown
+ * thrown Error maps to `ExitCode.Generic`.
+ */
+export class KnowzError extends Error {
+    exitCode;
+    constructor(message, exitCode = ExitCode.Generic, options) {
+        super(message);
+        this.name = 'KnowzError';
+        this.exitCode = exitCode;
+        if (options?.cause !== undefined)
+            this.cause = options.cause;
+    }
+}
+export function isKnowzError(e) {
+    return e instanceof KnowzError;
+}
+/**
+ * Map any thrown value to a process exit code:
+ *  - KnowzError → its declared exitCode
+ *  - ApiError   → 404 NotFound(5), 401/403 Auth(3), else Api(4)
+ *  - anything else → Generic(1)
+ */
+export function exitCodeForError(e) {
+    if (isKnowzError(e))
+        return e.exitCode;
+    if (isApiError(e)) {
+        if (e.status === 404)
+            return ExitCode.NotFound;
+        if (e.status === 401 || e.status === 403)
+            return ExitCode.Auth;
+        return ExitCode.Api;
+    }
+    return ExitCode.Generic;
+}
+/** Structural check for ApiError without importing the class (avoids a type/runtime coupling). */
+function isApiError(e) {
+    return (typeof e === 'object' &&
+        e !== null &&
+        e.name === 'ApiError' &&
+        typeof e.status === 'number');
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,GAAG,EAAE,CAAC;IACN,QAAQ,EAAE,CAAC;CACH,CAAC;AAIX;;;;GAIG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,QAAQ,CAAgB;IAEjC,YAAY,OAAe,EAAE,WAA0B,QAAQ,CAAC,OAAO,EAAE,OAA6B;QACpG,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,OAAO,EAAE,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC/D,CAAC;CACF;AAED,MAAM,UAAU,YAAY,CAAC,CAAU;IACrC,OAAO,CAAC,YAAY,UAAU,CAAC;AACjC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAU;IACzC,IAAI,YAAY,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,QAAQ,CAAC;IACvC,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;QAClB,IAAI,CAAC,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,QAAQ,CAAC,QAAQ,CAAC;QAC/C,IAAI,CAAC,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,QAAQ,CAAC,IAAI,CAAC;QAC/D,OAAO,QAAQ,CAAC,GAAG,CAAC;IACtB,CAAC;IACD,OAAO,QAAQ,CAAC,OAAO,CAAC;AAC1B,CAAC;AAED,kGAAkG;AAClG,SAAS,UAAU,CAAC,CAAU;IAC5B,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACT,CAAwB,CAAC,IAAI,KAAK,UAAU;QAC7C,OAAQ,CAA0B,CAAC,MAAM,KAAK,QAAQ,CACvD,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './errors.js';
+export * from './logger.js';
+export * from './config.js';
+export * from './credential-store.js';
+export * from './redactor.js';
+export * from './auth.js';
+export * from './settings.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './errors.js';
+export * from './logger.js';
+export * from './config.js';
+export * from './credential-store.js';
+export * from './redactor.js';
+export * from './auth.js';
+export * from './settings.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Structured logger with a pluggable secret redactor seam.
+ *
+ * N1 ships a no-op redactor; N3 installs the real secret-redaction filter via
+ * `logger.setRedactor(...)` during CLI startup, BEFORE any auth command runs.
+ * Human/log output goes to stderr; machine output (`--json`) is written to
+ * stdout by commands directly (not through this logger).
+ */
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+export type Redactor = (text: string) => string;
+export declare class Logger {
+    level: LogLevel;
+    private redactor;
+    setRedactor(r: Redactor): void;
+    setLevel(level: LogLevel): void;
+    private write;
+    error(msg: string, meta?: unknown): void;
+    warn(msg: string, meta?: unknown): void;
+    info(msg: string, meta?: unknown): void;
+    debug(msg: string, meta?: unknown): void;
+    /** Redact an arbitrary string using the installed redactor (for error rendering). */
+    redact(text: string): string;
+}
+/** Process-wide logger singleton. */
+export declare const logger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAC3D,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAUhD,qBAAa,MAAM;IACjB,KAAK,EAAE,QAAQ,CAAyB;IACxC,OAAO,CAAC,QAAQ,CAAsB;IAEtC,WAAW,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI;IAI9B,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B,OAAO,CAAC,KAAK;IAWb,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAGxC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAGvC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAGvC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAIxC,qFAAqF;IACrF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAG7B;AAUD,qCAAqC;AACrC,eAAO,MAAM,MAAM,QAAe,CAAC"}