gavio 0.1.0

package/dist/esm/interceptors/pii/scanners/iban.js

@@ -0,0 +1,54 @@
+/** IBAN scanner — regex candidate + ISO 13616 mod-97 checksum validation. */
+import { makeMatch } from '../match.js';
+// Candidate: 2 letters, 2 check digits, 11–30 alphanumerics (optionally spaced).
+const IBAN = /\b[A-Z]{2}\d{2}(?:[ ]?[A-Z0-9]){11,30}\b/g;
+/** ISO 13616 mod-97: rearrange, convert letters to numbers, check %97 == 1. */
+export function validIban(candidate) {
+    const cleaned = candidate.replace(/ /g, '').toUpperCase();
+    if (cleaned.length < 15)
+        return false;
+    const rearranged = cleaned.slice(4) + cleaned.slice(0, 4);
+    let digits = '';
+    for (const ch of rearranged) {
+        if (ch >= 'A' && ch <= 'Z') {
+            digits += (ch.charCodeAt(0) - 55).toString();
+        }
+        else if (ch >= '0' && ch <= '9') {
+            digits += ch;
+        }
+        else {
+            return false;
+        }
+    }
+    return mod97(digits) === 1;
+}
+/** Compute n % 97 over a large numeric string without BigInt overflow concerns. */
+function mod97(numeric) {
+    let remainder = 0;
+    for (const ch of numeric) {
+        remainder = (remainder * 10 + (ch.charCodeAt(0) - 48)) % 97;
+    }
+    return remainder;
+}
+export function ibanScanner() {
+    return {
+        entityType: 'IBAN',
+        tier: 1,
+        scan(text, ctx) {
+            const out = [];
+            for (const m of text.matchAll(IBAN)) {
+                if (!validIban(m[0]))
+                    continue;
+                const idx = ctx.nextIndex('IBAN');
+                out.push(makeMatch({
+                    entityType: 'IBAN',
+                    start: m.index,
+                    end: m.index + m[0].length,
+                    value: m[0],
+                    replacement: `[IBAN_${idx}]`,
+                }));
+            }
+            return out;
+        },
+    };
+}

package/dist/esm/interceptors/pii/scanners/index.d.ts

@@ -0,0 +1,13 @@
+/** Built-in tier-1 (regex) PII scanners. */
+import type { PiiScanner } from '../scanner.js';
+export { bsnScanner, validBsn } from './bsn.js';
+export { creditCardScanner, luhnValid } from './credit-card.js';
+export { emailScanner } from './email.js';
+export { ibanScanner, validIban } from './iban.js';
+export { ipAddressScanner } from './ip-address.js';
+export { phoneScanner } from './phone.js';
+export type { PhoneScannerOptions } from './phone.js';
+export { secretScanner } from './secret.js';
+export { ssnScanner } from './ssn.js';
+/** The default scanner set wired into PiiGuard when none is supplied. */
+export declare function defaultScanners(): PiiScanner[];

package/dist/esm/interceptors/pii/scanners/index.js

@@ -0,0 +1,30 @@
+/** Built-in tier-1 (regex) PII scanners. */
+import { bsnScanner } from './bsn.js';
+import { creditCardScanner } from './credit-card.js';
+import { emailScanner } from './email.js';
+import { ibanScanner } from './iban.js';
+import { ipAddressScanner } from './ip-address.js';
+import { phoneScanner } from './phone.js';
+import { secretScanner } from './secret.js';
+import { ssnScanner } from './ssn.js';
+export { bsnScanner, validBsn } from './bsn.js';
+export { creditCardScanner, luhnValid } from './credit-card.js';
+export { emailScanner } from './email.js';
+export { ibanScanner, validIban } from './iban.js';
+export { ipAddressScanner } from './ip-address.js';
+export { phoneScanner } from './phone.js';
+export { secretScanner } from './secret.js';
+export { ssnScanner } from './ssn.js';
+/** The default scanner set wired into PiiGuard when none is supplied. */
+export function defaultScanners() {
+    return [
+        secretScanner(),
+        emailScanner(),
+        ibanScanner(),
+        bsnScanner(),
+        creditCardScanner(),
+        ssnScanner(),
+        phoneScanner(),
+        ipAddressScanner(),
+    ];
+}

package/dist/esm/interceptors/pii/scanners/ip-address.d.ts

@@ -0,0 +1,3 @@
+/** IP address scanner — IPv4 and IPv6, validated via node:net isIP. */
+import type { PiiScanner } from '../scanner.js';
+export declare function ipAddressScanner(): PiiScanner;

package/dist/esm/interceptors/pii/scanners/ip-address.js

@@ -0,0 +1,33 @@
+/** IP address scanner — IPv4 and IPv6, validated via node:net isIP. */
+import { isIP } from 'node:net';
+import { makeMatch } from '../match.js';
+const IPV4 = String.raw `(?:\d{1,3}\.){3}\d{1,3}`;
+// Permissive IPv6 candidate — allows empty groups for "::" compression. False
+// positives are filtered by isIP validation below.
+const IPV6 = String.raw `(?:[A-Fa-f0-9]{0,4}:){2,7}[A-Fa-f0-9]{0,4}`;
+const IP = new RegExp(String.raw `(?<![\w.])(?:${IPV6}|${IPV4})(?![\w.])`, 'g');
+function validIp(candidate) {
+    return isIP(candidate) !== 0;
+}
+export function ipAddressScanner() {
+    return {
+        entityType: 'IP_ADDRESS',
+        tier: 1,
+        scan(text, ctx) {
+            const out = [];
+            for (const m of text.matchAll(IP)) {
+                if (!validIp(m[0]))
+                    continue;
+                const idx = ctx.nextIndex('IP_ADDRESS');
+                out.push(makeMatch({
+                    entityType: 'IP_ADDRESS',
+                    start: m.index,
+                    end: m.index + m[0].length,
+                    value: m[0],
+                    replacement: `[IP_ADDRESS_${idx}]`,
+                }));
+            }
+            return out;
+        },
+    };
+}

package/dist/esm/interceptors/pii/scanners/phone.d.ts

@@ -0,0 +1,6 @@
+/** Phone number scanner — E.164 and common national formats. */
+import type { PiiScanner } from '../scanner.js';
+export interface PhoneScannerOptions {
+    locales?: string[];
+}
+export declare function phoneScanner(options?: PhoneScannerOptions): PiiScanner;

package/dist/esm/interceptors/pii/scanners/phone.js

@@ -0,0 +1,34 @@
+/** Phone number scanner — E.164 and common national formats. */
+import { makeMatch } from '../match.js';
+// E.164 (+CC...) or national groupings with separators. A digit-count filter
+// (7–15) below avoids matching short numbers / years.
+const PHONE = /(?<![\w.])(?:\+?\d{1,3}[ .-]?)?(?:\(\d{1,4}\)[ .-]?)?\d{2,4}(?:[ .-]?\d{2,4}){2,4}(?![\w])/g;
+export function phoneScanner(options = {}) {
+    const locales = options.locales ?? ['NL', 'DE', 'GB', 'US'];
+    return {
+        entityType: 'PHONE',
+        tier: 1,
+        confidence: 0.85,
+        scan(text, ctx) {
+            const out = [];
+            for (const m of text.matchAll(PHONE)) {
+                const digitCount = (m[0].match(/\d/g) ?? []).length;
+                if (digitCount < 7 || digitCount > 15)
+                    continue;
+                const idx = ctx.nextIndex('PHONE');
+                out.push(makeMatch({
+                    entityType: 'PHONE',
+                    start: m.index,
+                    end: m.index + m[0].length,
+                    value: m[0],
+                    confidence: 0.85,
+                    replacement: `[PHONE_${idx}]`,
+                }));
+            }
+            return out;
+        },
+        supportsLocale(locale) {
+            return locales.includes(locale.toUpperCase());
+        },
+    };
+}

package/dist/esm/interceptors/pii/scanners/secret.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Secret / credential scanner (F-SEC-04).
+ *
+ * Detects API keys, tokens, JWTs, PEM private keys, and database connection
+ * strings. These must never leave the device, so SecretScanner is tier 1 and
+ * runs by default.
+ */
+import type { PiiScanner } from '../scanner.js';
+export declare function secretScanner(): PiiScanner;

package/dist/esm/interceptors/pii/scanners/secret.js

@@ -0,0 +1,43 @@
+/**
+ * Secret / credential scanner (F-SEC-04).
+ *
+ * Detects API keys, tokens, JWTs, PEM private keys, and database connection
+ * strings. These must never leave the device, so SecretScanner is tier 1 and
+ * runs by default.
+ */
+import { makeMatch } from '../match.js';
+// [label, pattern] — ordered most-specific first. All patterns are global.
+const PATTERNS = [
+    ['ANTHROPIC_KEY', /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g],
+    ['OPENAI_KEY', /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/g],
+    ['AWS_ACCESS_KEY', /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g],
+    ['GITHUB_TOKEN', /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g],
+    ['JWT', /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g],
+    ['PRIVATE_KEY', /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/g],
+    [
+        'DB_CONNECTION_STRING',
+        /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis):\/\/[^\s"']+/g,
+    ],
+];
+export function secretScanner() {
+    return {
+        entityType: 'SECRET',
+        tier: 1,
+        scan(text, ctx) {
+            const out = [];
+            for (const [, pattern] of PATTERNS) {
+                for (const m of text.matchAll(pattern)) {
+                    const idx = ctx.nextIndex('SECRET');
+                    out.push(makeMatch({
+                        entityType: 'SECRET',
+                        start: m.index,
+                        end: m.index + m[0].length,
+                        value: m[0],
+                        replacement: `[SECRET_${idx}]`,
+                    }));
+                }
+            }
+            return out;
+        },
+    };
+}

package/dist/esm/interceptors/pii/scanners/ssn.d.ts

@@ -0,0 +1,3 @@
+/** US Social Security Number scanner. */
+import type { PiiScanner } from '../scanner.js';
+export declare function ssnScanner(): PiiScanner;

package/dist/esm/interceptors/pii/scanners/ssn.js

@@ -0,0 +1,25 @@
+/** US Social Security Number scanner. */
+import { makeMatch } from '../match.js';
+// AAA-GG-SSSS with hyphens or spaces. Requires a separator to avoid colliding
+// with bare 9-digit numbers (handled by the BSN scanner / others).
+const SSN = /\b(?!000|666|9\d\d)\d{3}[ -](?!00)\d{2}[ -](?!0000)\d{4}\b/g;
+export function ssnScanner() {
+    return {
+        entityType: 'SSN',
+        tier: 1,
+        scan(text, ctx) {
+            const out = [];
+            for (const m of text.matchAll(SSN)) {
+                const idx = ctx.nextIndex('SSN');
+                out.push(makeMatch({
+                    entityType: 'SSN',
+                    start: m.index,
+                    end: m.index + m[0].length,
+                    value: m[0],
+                    replacement: `[SSN_${idx}]`,
+                }));
+            }
+            return out;
+        },
+    };
+}

package/dist/esm/interceptors/reliability/fallback.d.ts

@@ -0,0 +1,9 @@
+/** fallbackChain (F-REL-02) — route to a secondary provider on failure. */
+import type { ProviderAdapter } from '../../providers/base.js';
+import type { ExecutorPolicy } from '../base.js';
+export interface FallbackChainOptions {
+    /** Provider adapters to try, in order, when the primary call fails. */
+    fallbacks: ProviderAdapter[];
+}
+/** Factory: build a fallback policy. */
+export declare function fallbackChain(options: FallbackChainOptions): ExecutorPolicy;

package/dist/esm/interceptors/reliability/fallback.js

@@ -0,0 +1,50 @@
+/** fallbackChain (F-REL-02) — route to a secondary provider on failure. */
+import { ProviderError } from '../../errors.js';
+import { coerceProvider } from '../../types.js';
+/**
+ * Try the primary executor; on a provider error, try fallback adapters.
+ *
+ * Each fallback is a provider adapter (anything with an async `complete`). The
+ * request's provider/model are rewritten per fallback so the audit record
+ * reflects which provider actually answered.
+ */
+class FallbackChain {
+    name = 'fallback';
+    isExecutorPolicy = true;
+    dryRunSafe = true;
+    fallbacks;
+    constructor(options) {
+        if (!options.fallbacks || options.fallbacks.length === 0) {
+            throw new Error('fallbackChain requires at least one fallback adapter');
+        }
+        this.fallbacks = options.fallbacks;
+    }
+    async around(request, ctx, callNext) {
+        ctx.markFired(this.name);
+        try {
+            return await callNext(request);
+        }
+        catch (primaryError) {
+            if (!(primaryError instanceof ProviderError))
+                throw primaryError;
+            let lastError = primaryError;
+            for (const adapter of this.fallbacks) {
+                try {
+                    const rerouted = request.copyWithMessages(request.messages);
+                    rerouted.provider = coerceProvider(adapter.providerName);
+                    return await adapter.complete(rerouted);
+                }
+                catch (error) {
+                    if (!(error instanceof ProviderError))
+                        throw error;
+                    lastError = error;
+                }
+            }
+            throw lastError;
+        }
+    }
+}
+/** Factory: build a fallback policy. */
+export function fallbackChain(options) {
+    return new FallbackChain(options);
+}

package/dist/esm/interceptors/reliability/index.d.ts

@@ -0,0 +1,7 @@
+/** Reliability policies (F-REL-01, F-REL-02, F-REL-07). */
+export { retryInterceptor } from './retry.js';
+export type { RetryInterceptorOptions } from './retry.js';
+export { timeoutPolicy, timeout } from './timeout.js';
+export type { TimeoutPolicyOptions } from './timeout.js';
+export { fallbackChain } from './fallback.js';
+export type { FallbackChainOptions } from './fallback.js';

package/dist/esm/interceptors/reliability/index.js

@@ -0,0 +1,4 @@
+/** Reliability policies (F-REL-01, F-REL-02, F-REL-07). */
+export { retryInterceptor } from './retry.js';
+export { timeoutPolicy, timeout } from './timeout.js';
+export { fallbackChain } from './fallback.js';

package/dist/esm/interceptors/reliability/retry.d.ts

@@ -0,0 +1,13 @@
+/** retryInterceptor (F-REL-01) — exponential backoff with jitter. */
+import type { ExecutorPolicy } from '../base.js';
+export interface RetryInterceptorOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitter?: boolean;
+    retryOn?: (error: unknown) => boolean;
+    /** Override the sleep implementation (used in tests). */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Factory: build a retry policy. */
+export declare function retryInterceptor(options?: RetryInterceptorOptions): ExecutorPolicy;

package/dist/esm/interceptors/reliability/retry.js

@@ -0,0 +1,66 @@
+/** retryInterceptor (F-REL-01) — exponential backoff with jitter. */
+import { randomBytes } from 'node:crypto';
+import { ProviderUnavailableError, RateLimitError, ServerError, TimeoutError, } from '../../errors.js';
+/** Default predicate: retry transient provider errors. */
+function defaultRetryable(error) {
+    return (error instanceof RateLimitError ||
+        error instanceof TimeoutError ||
+        error instanceof ServerError ||
+        error instanceof ProviderUnavailableError);
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+class RetryInterceptor {
+    name = 'retry';
+    isExecutorPolicy = true;
+    dryRunSafe = true;
+    maxAttempts;
+    baseDelayMs;
+    maxDelayMs;
+    jitter;
+    retryOn;
+    sleep;
+    constructor(options = {}) {
+        const maxAttempts = options.maxAttempts ?? 3;
+        if (maxAttempts < 1)
+            throw new Error('maxAttempts must be >= 1');
+        this.maxAttempts = maxAttempts;
+        this.baseDelayMs = options.baseDelayMs ?? 500;
+        this.maxDelayMs = options.maxDelayMs ?? 10_000;
+        this.jitter = options.jitter ?? true;
+        this.retryOn = options.retryOn ?? defaultRetryable;
+        this.sleep = options.sleep ?? defaultSleep;
+    }
+    async around(request, ctx, callNext) {
+        ctx.markFired(this.name);
+        let lastError;
+        for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+            try {
+                return await callNext(request);
+            }
+            catch (error) {
+                if (!this.retryOn(error))
+                    throw error;
+                lastError = error;
+                if (attempt >= this.maxAttempts)
+                    break;
+                await this.sleep(this.delayMs(attempt));
+            }
+        }
+        throw lastError;
+    }
+    delayMs(attempt) {
+        // Exponential: base * 2^(attempt-1), capped, with optional full jitter.
+        const raw = this.baseDelayMs * 2 ** (attempt - 1);
+        let capped = Math.min(raw, this.maxDelayMs);
+        if (this.jitter) {
+            // full jitter in [0, capped] using crypto bytes (no global RNG state)
+            const frac = randomBytes(2).readUInt16BE(0) / 0xffff;
+            capped *= frac;
+        }
+        return capped;
+    }
+}
+/** Factory: build a retry policy. */
+export function retryInterceptor(options = {}) {
+    return new RetryInterceptor(options);
+}

package/dist/esm/interceptors/reliability/timeout.d.ts

@@ -0,0 +1,9 @@
+/** timeoutPolicy (F-REL-07) — per-request timeout enforcement. */
+import type { ExecutorPolicy } from '../base.js';
+export interface TimeoutPolicyOptions {
+    timeoutSeconds?: number;
+}
+/** Factory: build a timeout policy. */
+export declare function timeoutPolicy(options?: TimeoutPolicyOptions): ExecutorPolicy;
+/** Alias matching the SDK plan naming (`timeout`). */
+export declare const timeout: typeof timeoutPolicy;

package/dist/esm/interceptors/reliability/timeout.js

@@ -0,0 +1,37 @@
+/** timeoutPolicy (F-REL-07) — per-request timeout enforcement. */
+import { TimeoutError } from '../../errors.js';
+class TimeoutPolicy {
+    name = 'timeout';
+    isExecutorPolicy = true;
+    dryRunSafe = true;
+    timeoutSeconds;
+    constructor(options = {}) {
+        const timeoutSeconds = options.timeoutSeconds ?? 30.0;
+        if (timeoutSeconds <= 0)
+            throw new Error('timeoutSeconds must be > 0');
+        this.timeoutSeconds = timeoutSeconds;
+    }
+    async around(request, ctx, callNext) {
+        ctx.markFired(this.name);
+        const ms = this.timeoutSeconds * 1000;
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                reject(new TimeoutError(`Request exceeded ${this.timeoutSeconds}s timeout`));
+            }, ms);
+        });
+        try {
+            return await Promise.race([callNext(request), timeout]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+}
+/** Factory: build a timeout policy. */
+export function timeoutPolicy(options = {}) {
+    return new TimeoutPolicy(options);
+}
+/** Alias matching the SDK plan naming (`timeout`). */
+export const timeout = timeoutPolicy;

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/pricing.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Token cost tracking (F-GOV-01).
+ *
+ * Prices are USD per 1,000 tokens, sourced from public provider pricing and
+ * overridable. Unknown models price at zero (warned once) rather than guessing.
+ * Prices are intentionally data, not code — update the table, not the estimator.
+ */
+import type { TokenUsage } from './types.js';
+/** Estimates request cost from token usage and a model price table. */
+export declare class PricingProvider {
+    private prices;
+    private warned;
+    constructor(prices?: Record<string, [number, number]>);
+    setPrice(model: string, inputPer1k: number, outputPer1k: number): void;
+    rates(model: string): [number, number];
+    estimate(model: string, usage: TokenUsage): number;
+}
+/** Rough token estimate (~4 chars/token) for providers without a tokenizer. */
+export declare function estimateTokens(text: string): number;

package/dist/esm/pricing.js

@@ -0,0 +1,65 @@
+/**
+ * Token cost tracking (F-GOV-01).
+ *
+ * Prices are USD per 1,000 tokens, sourced from public provider pricing and
+ * overridable. Unknown models price at zero (warned once) rather than guessing.
+ * Prices are intentionally data, not code — update the table, not the estimator.
+ */
+/** model -> [inputPer1kUsd, outputPer1kUsd] */
+const DEFAULT_PRICES = {
+    // OpenAI
+    'gpt-4o': [0.0025, 0.01],
+    'gpt-4o-mini': [0.00015, 0.0006],
+    o1: [0.015, 0.06],
+    'o1-mini': [0.0011, 0.0044],
+    // Anthropic
+    'claude-sonnet-4-6': [0.003, 0.015],
+    'claude-sonnet-4-20250514': [0.003, 0.015],
+    'claude-haiku-4-5': [0.0008, 0.004],
+    'claude-opus-4-1': [0.015, 0.075],
+    // Local / mock are free.
+    mock: [0.0, 0.0],
+};
+/** Estimates request cost from token usage and a model price table. */
+export class PricingProvider {
+    prices;
+    warned = new Set();
+    constructor(prices) {
+        this.prices = { ...DEFAULT_PRICES, ...(prices ?? {}) };
+    }
+    setPrice(model, inputPer1k, outputPer1k) {
+        this.prices[model] = [inputPer1k, outputPer1k];
+    }
+    rates(model) {
+        const rate = this.prices[model];
+        if (rate !== undefined)
+            return rate;
+        // try a prefix match (e.g. "gpt-4o-2024-..." -> "gpt-4o")
+        for (const [known, value] of Object.entries(this.prices)) {
+            if (model.startsWith(known))
+                return value;
+        }
+        if (!this.warned.has(model)) {
+            // eslint-disable-next-line no-console
+            console.warn(`[gavio:pricing] no pricing for model '${model}'; treating as free`);
+            this.warned.add(model);
+        }
+        return [0.0, 0.0];
+    }
+    estimate(model, usage) {
+        const [inRate, outRate] = this.rates(model);
+        let cost = (usage.promptTokens / 1000.0) * inRate;
+        cost += (usage.completionTokens / 1000.0) * outRate;
+        return roundTo(cost, 8);
+    }
+}
+function roundTo(value, decimals) {
+    const factor = 10 ** decimals;
+    return Math.round(value * factor) / factor;
+}
+/** Rough token estimate (~4 chars/token) for providers without a tokenizer. */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.max(1, Math.floor(text.length / 4));
+}

package/dist/esm/providers/anthropic.d.ts

@@ -0,0 +1,30 @@
+/** anthropicAdapter — Messages API (Claude Sonnet, Haiku, Opus). */
+import type { PricingProvider } from '../pricing.js';
+import type { GavioRequest } from '../request.js';
+import type { GavioResponse } from '../response.js';
+import { BaseProviderAdapter } from './base.js';
+export interface AnthropicAdapterOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    pricing?: PricingProvider;
+}
+/**
+ * Talks to the Anthropic Messages endpoint. Anthropic splits the system prompt
+ * from the message list, so any `role === "system"` messages are extracted into
+ * the `system` field.
+ */
+declare class AnthropicAdapter extends BaseProviderAdapter {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutSeconds;
+    constructor(options?: AnthropicAdapterOptions);
+    get providerName(): string;
+    private headers;
+    private static splitSystem;
+    complete(request: GavioRequest): Promise<GavioResponse>;
+    healthCheck(): Promise<boolean>;
+}
+/** Factory: build an Anthropic provider adapter. */
+export declare function anthropicAdapter(options?: AnthropicAdapterOptions): AnthropicAdapter;
+export {};