@envseal/core 0.1.0

package/dist/tickets.js

@@ -0,0 +1,179 @@
+/**
+ * In-memory ticket store. Records live only for the lifetime of the process and
+ * are NEVER persisted anywhere. They hold metadata and per-key *outcomes*
+ * (strings only) — never secret values.
+ */
+import { randomInt } from 'node:crypto';
+import { ulid } from 'ulid';
+const CROCKFORD_BASE32 = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+function makeNonce() {
+    let chars = '';
+    for (let i = 0; i < 8; i++) {
+        chars += CROCKFORD_BASE32[randomInt(CROCKFORD_BASE32.length)];
+    }
+    return `${chars.slice(0, 4)}-${chars.slice(4)}`;
+}
+const DEFAULT_TTL_MS = 600_000;
+const SWEEP_INTERVAL_MS = 60_000;
+/** setTimeout silently fires immediately past this, which would settle early. */
+const MAX_TIMER_MS = 2_147_483_647;
+export class TicketStore {
+    records = new Map();
+    waiters = new Map();
+    pendingAwaits = new Set();
+    timer;
+    defaultTtlMs;
+    constructor(options = {}) {
+        this.defaultTtlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.timer = setInterval(() => this.sweep(), options.sweepIntervalMs ?? SWEEP_INTERVAL_MS);
+        this.timer.unref();
+    }
+    create(opts) {
+        const createdAt = Date.now();
+        const record = {
+            ticket: ulid(),
+            nonce: makeNonce(),
+            keys: [...opts.keys],
+            reason: opts.reason,
+            surface: opts.surface,
+            createdAt,
+            expiresAt: createdAt + (opts.ttlMs ?? this.defaultTtlMs),
+            state: 'pending',
+            outcomes: new Map(),
+        };
+        this.records.set(record.ticket, record);
+        return record;
+    }
+    get(ticket) {
+        return this.records.get(ticket);
+    }
+    setOutcome(ticket, key, outcome) {
+        const record = this.records.get(ticket);
+        if (!record)
+            return;
+        record.outcomes.set(key, outcome);
+    }
+    resolve(ticket) {
+        const record = this.records.get(ticket);
+        if (!record || record.state !== 'pending')
+            return;
+        record.state = 'resolved';
+        this.bump(ticket);
+    }
+    cancel(ticket) {
+        const record = this.records.get(ticket);
+        if (!record || record.state !== 'pending')
+            return;
+        record.state = 'cancelled';
+        this.bump(ticket);
+    }
+    sweep(now = Date.now()) {
+        for (const record of this.records.values()) {
+            this.expireIfDue(record, now);
+        }
+    }
+    /**
+     * F-W7-6: expiry used to be computed only by the 60s sweep, so an await that
+     * outlived a shorter TTL reported `pending` rather than `expired`. Every
+     * caller that can observe a record evaluates `expiresAt` itself.
+     */
+    expireIfDue(record, now = Date.now()) {
+        if (record.state === 'pending' && record.expiresAt <= now) {
+            record.state = 'expired';
+            this.bump(record.ticket);
+        }
+    }
+    await(ticket, timeoutMs) {
+        return new Promise((resolvePromise) => {
+            const record = this.records.get(ticket);
+            if (!record) {
+                resolvePromise({ ticket, state: 'expired', keys: [] });
+                return;
+            }
+            this.expireIfDue(record);
+            let settled = false;
+            let timeout;
+            const listener = () => {
+                if (record.state !== 'pending')
+                    finish();
+            };
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.unsubscribe(ticket, listener);
+                this.pendingAwaits.delete(finish);
+                if (timeout !== undefined)
+                    clearTimeout(timeout);
+                resolvePromise(this.toOutcome(record));
+            };
+            if (record.state !== 'pending') {
+                finish();
+                return;
+            }
+            // Wake at whichever comes first: the caller's timeout, or the ticket's
+            // own expiry.
+            const untilExpiry = Math.max(0, record.expiresAt - Date.now());
+            const delay = Math.min(Math.max(0, timeoutMs), untilExpiry, MAX_TIMER_MS);
+            timeout = setTimeout(() => {
+                this.expireIfDue(record);
+                finish();
+            }, delay);
+            // NOT unref'd. F-W7-6: an unref'd timer let the process exit with this
+            // promise never settled — Node reported "Detected unsettled top-level
+            // await" and exited 13 with no output at all. An outstanding await is an
+            // outstanding operation and must hold the loop open; it is cleared the
+            // moment the promise settles, and dispose() settles it too.
+            this.pendingAwaits.add(finish);
+            this.subscribe(ticket, listener);
+        });
+    }
+    dispose() {
+        clearInterval(this.timer);
+        for (const listeners of this.waiters.values()) {
+            for (const listener of listeners)
+                listener();
+        }
+        // Settle anything still waiting, so a disposed store can never leave a
+        // ref'd timer (or a caller's promise) hanging.
+        for (const finish of [...this.pendingAwaits])
+            finish();
+        this.pendingAwaits.clear();
+        this.waiters.clear();
+        this.records.clear();
+    }
+    toOutcome(record) {
+        const keys = [...record.outcomes.entries()].map(([key, outcome]) => ({ key, outcome }));
+        return { ticket: record.ticket, state: record.state, keys };
+    }
+    subscribe(ticket, listener) {
+        let set = this.waiters.get(ticket);
+        if (set === undefined) {
+            set = new Set();
+            this.waiters.set(ticket, set);
+        }
+        set.add(listener);
+    }
+    unsubscribe(ticket, listener) {
+        const set = this.waiters.get(ticket);
+        if (set === undefined)
+            return;
+        set.delete(listener);
+        if (set.size === 0)
+            this.waiters.delete(ticket);
+    }
+    bump(ticket) {
+        const set = this.waiters.get(ticket);
+        if (set === undefined)
+            return;
+        for (const listener of set) {
+            try {
+                listener();
+            }
+            catch {
+                // listeners must never throw out of a state transition
+            }
+        }
+    }
+}
+//# sourceMappingURL=tickets.js.map

package/dist/validation-state.d.ts

@@ -0,0 +1,33 @@
+import type { ProjectPaths } from './paths.js';
+/**
+ * Persisted format-validation outcomes.
+ *
+ * This exists to close a chosen-predicate oracle. `env_describe` used to compile
+ * the manifest's `format.pattern` — a value the MODEL supplies via `env_declare`
+ * — and test it against the live stored secret, returning the boolean. A model
+ * could therefore declare `^sk-a`, read the answer, declare `^sk-b`, and
+ * reconstruct the whole value one predicate at a time: W2's probe recovered a
+ * 33-character secret in 424 calls, with no user interaction and nothing
+ * secret-derived ever crossing the wire. The redactor is structurally incapable
+ * of catching that, because the value is reassembled from booleans inside the
+ * model's own context.
+ *
+ * The fix is to make the answer not depend on a model-chosen question: validate
+ * once, when the value is stored, and afterwards report the recorded outcome.
+ * Re-declaring a different pattern changes what future entries are checked
+ * against; it cannot re-interrogate a value that is already stored.
+ */
+export interface ValidationRecord {
+    /** Fingerprint of the value this outcome was computed for. */
+    fingerprint: string;
+    formatValid: boolean;
+    at: string;
+}
+export declare function recordValidation(paths: ProjectPaths, key: string, fingerprint: string, formatValid: boolean): void;
+/**
+ * The recorded outcome for a value, or null when we have not validated THIS
+ * value. Null means "unknown" and must be reported as such — guessing here
+ * would reopen the oracle.
+ */
+export declare function getValidation(paths: ProjectPaths, key: string, fingerprint: string): boolean | null;
+//# sourceMappingURL=validation-state.d.ts.map

package/dist/validation-state.js

@@ -0,0 +1,48 @@
+import { readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import { ensureStateDir } from './paths.js';
+function statePath(paths) {
+    return paths.stateDir.endsWith('.envseal')
+        ? `${paths.stateDir}/validation.json`
+        : `${paths.stateDir}/validation.json`;
+}
+function load(paths) {
+    try {
+        const parsed = JSON.parse(readFileSync(statePath(paths), 'utf8'));
+        if (parsed !== null && typeof parsed === 'object')
+            return parsed;
+    }
+    catch {
+        // Missing or unreadable: no recorded outcomes, which is reported as unknown
+        // rather than silently re-evaluated.
+    }
+    return {};
+}
+export function recordValidation(paths, key, fingerprint, formatValid) {
+    ensureStateDir(paths);
+    const all = load(paths);
+    all[key] = { fingerprint, formatValid, at: new Date().toISOString() };
+    const file = statePath(paths);
+    writeFileSync(file, `${JSON.stringify(all, null, 2)}\n`, 'utf8');
+    if (process.platform !== 'win32') {
+        try {
+            chmodSync(file, 0o600);
+        }
+        catch {
+            // best effort
+        }
+    }
+}
+/**
+ * The recorded outcome for a value, or null when we have not validated THIS
+ * value. Null means "unknown" and must be reported as such — guessing here
+ * would reopen the oracle.
+ */
+export function getValidation(paths, key, fingerprint) {
+    const record = load(paths)[key];
+    if (record === undefined)
+        return null;
+    if (record.fingerprint !== fingerprint)
+        return null;
+    return record.formatValid;
+}
+//# sourceMappingURL=validation-state.js.map

package/dist/verify.d.ts

@@ -0,0 +1,8 @@
+import type { ManifestEntry, SecretValue, VerifyResult } from '@envseal/protocol';
+import type { ProjectPaths } from './paths.js';
+export interface VerifyOptions {
+    timeoutMs?: number;
+    onApprovalNeeded?: (entry: ManifestEntry) => Promise<boolean>;
+}
+export declare function verifyKey(paths: ProjectPaths, entry: ManifestEntry, value: SecretValue, opts?: VerifyOptions): Promise<VerifyResult>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.js

@@ -0,0 +1,133 @@
+import { isHostAllowlisted, isProbeApproved, recordProbeApproval } from './approvals.js';
+import { redact } from './redact.js';
+import { unsafeSecretToUtf8 } from './sinks/dotenv.js';
+export async function verifyKey(paths, entry, value, opts) {
+    const now = new Date().toISOString();
+    if (!entry.verify) {
+        return {
+            key: entry.key,
+            result: 'no_probe',
+            message: 'No verification probe configured',
+            checkedAt: now,
+        };
+    }
+    const { url, method, headerTemplate, expectStatus } = entry.verify;
+    if (!url.startsWith('https://')) {
+        return {
+            key: entry.key,
+            result: 'network_error',
+            message: 'Probe URL must use https://',
+            checkedAt: now,
+        };
+    }
+    if (url.includes('{{value}}')) {
+        return {
+            key: entry.key,
+            result: 'network_error',
+            message: 'Probe URL must not contain {{value}}',
+            checkedAt: now,
+        };
+    }
+    const urlObj = new URL(url);
+    const hostname = urlObj.hostname;
+    const allowlisted = isHostAllowlisted(url);
+    const approved = isProbeApproved(paths, entry);
+    if (!allowlisted && !approved) {
+        if (opts?.onApprovalNeeded) {
+            const userApproved = await opts.onApprovalNeeded(entry);
+            if (userApproved) {
+                recordProbeApproval(paths, entry);
+            }
+            else {
+                return {
+                    key: entry.key,
+                    result: 'probe_not_approved',
+                    message: `Probe to ${hostname} requires approval`,
+                    checkedAt: now,
+                };
+            }
+        }
+        else {
+            return {
+                key: entry.key,
+                result: 'probe_not_approved',
+                message: `Probe to ${hostname} requires approval`,
+                checkedAt: now,
+            };
+        }
+    }
+    const valueStr = unsafeSecretToUtf8(value);
+    const headers = {};
+    for (const [key, templateVal] of Object.entries(headerTemplate)) {
+        headers[key] = templateVal.replace(/\{\{value\}\}/g, valueStr);
+    }
+    const timeoutMs = opts?.timeoutMs ?? 10000;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            method,
+            headers,
+            redirect: 'manual',
+            signal: controller.signal,
+        });
+        const statusCode = response.status;
+        const expectedStatuses = expectStatus ?? [200];
+        if (expectedStatuses.includes(statusCode)) {
+            return {
+                key: entry.key,
+                result: 'ok',
+                message: `HTTP ${statusCode} from ${hostname}`,
+                checkedAt: now,
+            };
+        }
+        if (statusCode === 401) {
+            return {
+                key: entry.key,
+                result: 'auth_failed',
+                message: `HTTP 401 from ${hostname}`,
+                checkedAt: now,
+            };
+        }
+        if (statusCode === 403) {
+            return {
+                key: entry.key,
+                result: 'forbidden',
+                message: `HTTP 403 from ${hostname}`,
+                checkedAt: now,
+            };
+        }
+        if (statusCode === 429) {
+            return {
+                key: entry.key,
+                result: 'rate_limited',
+                message: `HTTP 429 from ${hostname}`,
+                checkedAt: now,
+            };
+        }
+        return {
+            key: entry.key,
+            result: 'auth_failed',
+            message: `HTTP ${statusCode} from ${hostname}`,
+            checkedAt: now,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        let result = 'network_error';
+        if (message.includes('abort')) {
+            result = 'network_error';
+        }
+        const sanitized = redact(message, [value]).text;
+        return {
+            key: entry.key,
+            result,
+            message: sanitized,
+            checkedAt: now,
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+//# sourceMappingURL=verify.js.map

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@envseal/core",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1",
+    "ulid": "^2.3.0",
+    "@envseal/protocol": "0.1.0",
+    "@envseal/registry": "0.1.0",
+    "@envseal/detector": "0.1.0",
+    "@envseal/prompters": "0.1.0"
+  },
+  "devDependencies": {
+    "fast-check": "^3.23.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}