@envseal/core 0.1.0

package/dist/sinks/sops.d.ts

@@ -0,0 +1,54 @@
+import type { SecretValue } from '@envseal/protocol';
+import type { ProjectPaths } from '../paths.js';
+import { CliSinkBase } from './cli-sink-base.js';
+import type { CliExecOptions, CliExecResult } from './cli-sink-base.js';
+export declare class SopsSink extends CliSinkBase {
+    readonly id = "sops";
+    protected readonly requiredCommands: string[];
+    protected unavailableReason(): string;
+    /**
+     * Single choke point for every spawn this sink makes, overridable in tests
+     * exactly like vault.ts's — Windows cannot spawn shebang scripts, so the
+     * scripted harness substitutes at this seam instead of staging a fake on
+     * PATH and leaving argv construction unexercised here.
+     */
+    protected run(args: readonly string[], options?: CliExecOptions): Promise<CliExecResult>;
+    /**
+     * sops needs a binary AND an encryption target it can resolve: creation
+     * rules from `<root>/.sops.yaml`, or an age recipient passed via --age from
+     * ENVSEAL_SOPS_AGE_RECIPIENT. DEcryption additionally needs the matching
+     * private key, which sops discovers itself (SOPS_AGE_KEY, SOPS_AGE_KEY_FILE,
+     * or its default config location) — unverifiable without attempting an
+     * operation, so the honest boundary is: available() says "this sink could
+     * store", and a missing identity fails loudly at operation time.
+     */
+    available(paths: ProjectPaths): Promise<boolean>;
+    /**
+     * Encrypts the staged plaintext IN PLACE, so the invocation carries only a
+     * path — never bytes. With .sops.yaml present its creation rules apply
+     * untouched; otherwise --age carries the configured recipient.
+     */
+    private encryptInPlace;
+    /** Decrypts the staged ciphertext IN PLACE; stdout/stderr stay diagnostics-only. */
+    private decryptInPlace;
+    /**
+     * Copies the current sidecar (or starts empty) into a fresh staging dir
+     * under .envseal/, runs the operation against the staged path, and removes
+     * the directory on every path out — a leaked plaintext temp would outlive
+     * the operation's purpose.
+     */
+    private withStagedSidecar;
+    read(paths: ProjectPaths, key: string): Promise<SecretValue | null>;
+    write(paths: ProjectPaths, key: string, value: SecretValue): Promise<void>;
+    remove(paths: ProjectPaths, key: string): Promise<boolean>;
+    /**
+     * Prerequisite probe plus the encryption-target check, whose absence gets a
+     * precise message instead of hiding behind the generic reason. Unlike the
+     * other sinks there is no server to authenticate to — what can be cheaply
+     * verified is binary + target; the decryption identity is sops' own
+     * discovery problem and fails loudly at operation time.
+     */
+    private requireReady;
+}
+export declare const sopsSink: SopsSink;
+//# sourceMappingURL=sops.d.ts.map

package/dist/sinks/sops.js

@@ -0,0 +1,254 @@
+import { existsSync, copyFileSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join, relative } from 'node:path';
+import { asSecret, SepError } from '@envseal/protocol';
+import { ensureStateDir } from '../paths.js';
+import { CliSinkBase, execCli } from './cli-sink-base.js';
+/**
+ * The sidecar this sink owns: a flat `KEY: value` YAML map at the project
+ * root whose values are always SOPS ciphertext. A sibling of `.env` rather
+ * than a resident of `.envseal/` because the point of the sops sink is an
+ * encrypted store that is reviewable and backupable like any artifact — but
+ * it must never be COMMITTED by accident (see assertGitSafe below), only
+ * deliberately.
+ */
+const SIDECAR_NAME = '.env.sealsops.yaml';
+function sidecarPath(paths) {
+    return join(paths.root, SIDECAR_NAME);
+}
+/**
+ * Same refusal dotenv.ts applies to `.env`, aimed at the sidecar: inside a
+ * git work tree the file must be ignored and untracked before any write.
+ * Duplicated rather than exported because dotenv's version is private by
+ * design and this check is six lines.
+ */
+function assertGitSafe(paths) {
+    try {
+        execFileSync('git', ['rev-parse', '--is-inside-work-tree'], {
+            cwd: paths.root,
+            stdio: 'ignore',
+        });
+    }
+    catch {
+        return; // not a git repo — nothing to protect against
+    }
+    const relPath = relative(paths.root, sidecarPath(paths));
+    try {
+        execFileSync('git', ['ls-files', '--error-unmatch', '--', relPath], {
+            cwd: paths.root,
+            stdio: 'ignore',
+        });
+        throw new SepError({ code: 'SEP_GITIGNORE_UNSAFE' });
+    }
+    catch (error) {
+        if (error instanceof SepError)
+            throw error;
+        // nonzero from ls-files = not tracked — continue to the ignore check
+    }
+    try {
+        execFileSync('git', ['check-ignore', '-q', relPath], { cwd: paths.root, stdio: 'ignore' });
+    }
+    catch {
+        throw new SepError({ code: 'SEP_GITIGNORE_UNSAFE' });
+    }
+}
+/**
+ * Parse the flat subset of YAML this sink writes: comments, blank lines, and
+ * `KEY: value` where value may be double-quoted. SOPS-encrypted values are
+ * single-line scalars (`KEY: ENC[AES256_GCM,data:...,type:str]`) so the rest-
+ * of-line rule covers them; multi-line scalars would need a real parser and
+ * are neither produced by serializeFlat nor accepted back. Nested blocks —
+ * sops writes its metadata under a top-level `sops:` key — are skipped by the
+ * key-shape test rather than parsed.
+ */
+function parseFlat(yamlText) {
+    const map = {};
+    for (const line of yamlText.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#') || trimmed.endsWith(':'))
+            continue;
+        const colonAt = line.indexOf(':');
+        if (colonAt === -1)
+            continue;
+        const key = line.slice(0, colonAt).trim();
+        if (!/^[A-Za-z0-9_-]+$/.test(key))
+            continue; // nested keys under sops: etc.
+        let value = line.slice(colonAt + 1).trim();
+        if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+            value = value.slice(1, -1);
+        }
+        map[key] = value;
+    }
+    return map;
+}
+function serializeFlat(map) {
+    return (Object.entries(map)
+        .map(([key, value]) => `${key}: ${value}`)
+        .join('\n') + '\n');
+}
+export class SopsSink extends CliSinkBase {
+    id = 'sops';
+    requiredCommands = ['sops'];
+    unavailableReason() {
+        return ('the sops CLI is not installed or no encryption target is configured '
+            + '(.sops.yaml creation rules at the project root or ENVSEAL_SOPS_AGE_RECIPIENT)');
+    }
+    /**
+     * Single choke point for every spawn this sink makes, overridable in tests
+     * exactly like vault.ts's — Windows cannot spawn shebang scripts, so the
+     * scripted harness substitutes at this seam instead of staging a fake on
+     * PATH and leaving argv construction unexercised here.
+     */
+    run(args, options = {}) {
+        return execCli('sops', [...args], options);
+    }
+    /**
+     * sops needs a binary AND an encryption target it can resolve: creation
+     * rules from `<root>/.sops.yaml`, or an age recipient passed via --age from
+     * ENVSEAL_SOPS_AGE_RECIPIENT. DEcryption additionally needs the matching
+     * private key, which sops discovers itself (SOPS_AGE_KEY, SOPS_AGE_KEY_FILE,
+     * or its default config location) — unverifiable without attempting an
+     * operation, so the honest boundary is: available() says "this sink could
+     * store", and a missing identity fails loudly at operation time.
+     */
+    async available(paths) {
+        if (!(await super.available(paths)))
+            return false;
+        return existsSync(join(paths.root, '.sops.yaml')) || process.env.ENVSEAL_SOPS_AGE_RECIPIENT !== undefined;
+    }
+    /**
+     * Encrypts the staged plaintext IN PLACE, so the invocation carries only a
+     * path — never bytes. With .sops.yaml present its creation rules apply
+     * untouched; otherwise --age carries the configured recipient.
+     */
+    async encryptInPlace(stagedPath, paths) {
+        const args = ['--encrypt', '--input-type', 'yaml', '--output-type', 'yaml'];
+        if (!existsSync(join(paths.root, '.sops.yaml'))) {
+            const recipient = process.env.ENVSEAL_SOPS_AGE_RECIPIENT;
+            if (recipient === undefined) {
+                throw new SepError({
+                    code: 'SEP_SINK_UNAVAILABLE',
+                    userMessage: `The ${this.id} sink is not available — no .sops.yaml creation rules at the project root and ENVSEAL_SOPS_AGE_RECIPIENT is unset.`,
+                });
+            }
+            args.push('--age', recipient);
+        }
+        args.push(stagedPath);
+        await this.run(args);
+    }
+    /** Decrypts the staged ciphertext IN PLACE; stdout/stderr stay diagnostics-only. */
+    async decryptInPlace(stagedPath) {
+        await this.run(['--decrypt', '--input-type', 'yaml', '--output-type', 'yaml', stagedPath]);
+    }
+    /**
+     * Copies the current sidecar (or starts empty) into a fresh staging dir
+     * under .envseal/, runs the operation against the staged path, and removes
+     * the directory on every path out — a leaked plaintext temp would outlive
+     * the operation's purpose.
+     */
+    async withStagedSidecar(paths, operate) {
+        ensureStateDir(paths);
+        const stagingDir = mkdtempSync(join(paths.stateDir, 'sops-'));
+        const staged = join(stagingDir, 'sidecar.yaml');
+        try {
+            const file = sidecarPath(paths);
+            if (existsSync(file))
+                copyFileSync(file, staged);
+            else
+                writeFileSync(staged, '', { mode: 0o600 });
+            await operate(staged);
+        }
+        finally {
+            rmSync(stagingDir, { recursive: true, force: true });
+        }
+    }
+    async read(paths, key) {
+        try {
+            await this.requireReady(paths);
+            const file = sidecarPath(paths);
+            if (!existsSync(file))
+                return null;
+            let map = {};
+            await this.withStagedSidecar(paths, async (staged) => {
+                await this.decryptInPlace(staged);
+                map = parseFlat(readFileSync(staged, 'utf8'));
+            });
+            const value = map[key];
+            if (value === undefined)
+                return null;
+            return asSecret(Buffer.from(value, 'utf8'));
+        }
+        catch (error) {
+            throw this.sinkFailure('read', error, key);
+        }
+    }
+    async write(paths, key, value) {
+        try {
+            await this.requireReady(paths);
+            assertGitSafe(paths);
+            await this.withStagedSidecar(paths, async (staged) => {
+                // An existing staged sidecar is ciphertext and must be decrypted back
+                // before merging; a first-ever write stages an empty file that sops
+                // must never be pointed at.
+                if (existsSync(staged) && readFileSync(staged, 'utf8').trim() !== '') {
+                    await this.decryptInPlace(staged);
+                }
+                const map = parseFlat(readFileSync(staged, 'utf8'));
+                map[key] = value.toString('utf8');
+                writeFileSync(staged, serializeFlat(map), { mode: 0o600 });
+                await this.encryptInPlace(staged, paths);
+                writeFileSync(sidecarPath(paths), readFileSync(staged), { mode: 0o600 });
+            });
+        }
+        catch (error) {
+            throw this.sinkFailure('write', error, key);
+        }
+    }
+    async remove(paths, key) {
+        try {
+            await this.requireReady(paths);
+            const file = sidecarPath(paths);
+            if (!existsSync(file))
+                return false;
+            let removed = false;
+            await this.withStagedSidecar(paths, async (staged) => {
+                await this.decryptInPlace(staged);
+                const map = parseFlat(readFileSync(staged, 'utf8'));
+                if (!(key in map))
+                    return;
+                delete map[key];
+                removed = true;
+                if (Object.keys(map).length === 0) {
+                    // Last entry gone: an encrypted file holding nothing is noise, not a store.
+                    rmSync(file);
+                    return;
+                }
+                writeFileSync(staged, serializeFlat(map), { mode: 0o600 });
+                await this.encryptInPlace(staged, paths);
+                writeFileSync(file, readFileSync(staged), { mode: 0o600 });
+            });
+            return removed;
+        }
+        catch (error) {
+            throw this.sinkFailure('remove', error, key);
+        }
+    }
+    /**
+     * Prerequisite probe plus the encryption-target check, whose absence gets a
+     * precise message instead of hiding behind the generic reason. Unlike the
+     * other sinks there is no server to authenticate to — what can be cheaply
+     * verified is binary + target; the decryption identity is sops' own
+     * discovery problem and fails loudly at operation time.
+     */
+    async requireReady(paths) {
+        await this.requirePrerequisites();
+        if (!existsSync(join(paths.root, '.sops.yaml')) && process.env.ENVSEAL_SOPS_AGE_RECIPIENT === undefined) {
+            throw new SepError({
+                code: 'SEP_SINK_UNAVAILABLE',
+                userMessage: `The ${this.id} sink is not available — no .sops.yaml creation rules at the project root and ENVSEAL_SOPS_AGE_RECIPIENT is unset.`,
+            });
+        }
+    }
+}
+export const sopsSink = new SopsSink();
+//# sourceMappingURL=sops.js.map

package/dist/sinks/types.d.ts

@@ -0,0 +1,10 @@
+import type { SecretValue } from '@envseal/protocol';
+import type { ProjectPaths } from '../paths.js';
+export interface Sink {
+    readonly id: string;
+    available(paths: ProjectPaths): Promise<boolean>;
+    read(paths: ProjectPaths, key: string): Promise<SecretValue | null>;
+    write(paths: ProjectPaths, key: string, value: SecretValue): Promise<void>;
+    remove(paths: ProjectPaths, key: string): Promise<boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sinks/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/sinks/vault.d.ts

@@ -0,0 +1,41 @@
+import type { SecretValue } from '@envseal/protocol';
+import type { ProjectPaths } from '../paths.js';
+import { CliSinkBase } from './cli-sink-base.js';
+import type { CliExecOptions, CliExecResult } from './cli-sink-base.js';
+/**
+ * Auth posture: the token reaches the CLI through its own discovery chain
+ * (VAULT_TOKEN or ~/.vault-token); this sink never passes -token=, which
+ * would put the credential in argv. Writes need create/update on
+ * `<mount>/envseal/*`; reads need read on the same paths.
+ */
+export declare class VaultSink extends CliSinkBase {
+    readonly id = "vault";
+    protected readonly requiredCommands: string[];
+    protected unavailableReason(): string;
+    /**
+     * Single choke point for every spawn this sink makes. Production resolves
+     * `vault` off PATH; tests substitute a fake provider here instead of staging
+     * one on PATH, because Windows cannot spawn shebang scripts directly and a
+     * PATH-only double would leave the parsing/error-mapping logic unexercised
+     * there (see vault-sink.test.ts).
+     */
+    protected run(args: readonly string[], options?: CliExecOptions): Promise<CliExecResult>;
+    /**
+     * Vault on PATH AND an address to talk to. The base probe deliberately
+     * checks binaries only — VAULT_ADDR-style configuration is validated here
+     * and at operation time, where its absence can produce a precise message.
+     */
+    available(_paths: ProjectPaths): Promise<boolean>;
+    read(paths: ProjectPaths, key: string): Promise<SecretValue | null>;
+    write(paths: ProjectPaths, key: string, value: SecretValue): Promise<void>;
+    remove(paths: ProjectPaths, key: string): Promise<boolean>;
+    /**
+     * Every operation re-probes the CLI — available() may have been consulted
+     * long before, and the binary can vanish in between — then demands
+     * VAULT_ADDR separately, whose absence gets its own precise message instead
+     * of hiding behind the generic reason.
+     */
+    private requireReady;
+}
+export declare const vaultSink: VaultSink;
+//# sourceMappingURL=vault.d.ts.map

package/dist/sinks/vault.js

@@ -0,0 +1,156 @@
+import { SepError, asSecret } from '@envseal/protocol';
+import { CliSinkBase, execCli, exitCodeOf } from './cli-sink-base.js';
+import { unsafeSecretToUtf8 } from './dotenv.js';
+/**
+ * The mount envseal writes into when ENVSEAL_VAULT_MOUNT does not override it.
+ * A dedicated mount (kv-v2) keeps project secrets out of whatever else lives
+ * under the provider's default namespace.
+ */
+const DEFAULT_MOUNT = 'secret';
+/**
+ * `vault kv get` reports a missing path as exit 2 ("No value found at ...").
+ * Encoded from vault's documented CLI behavior: no vault exists on the
+ * development machine this mapping was authored on, so the live round-trip
+ * suite in vault-sink.test.ts is what confirms it wherever a server exists.
+ */
+const KV_NO_VALUE_FOUND = 2;
+/** The exact stderr phrase vault prints for a missing path. */
+const NO_VALUE_FOUND_MARKER = 'No value found';
+/**
+ * Exit 2 alone is NOT absence: the same code carries permission denied and
+ * every other API error. Only the "No value found" marker on stderr does —
+ * checking it keeps a forbidden path a loud SEP_SINK_WRITE_FAILED instead of
+ * a silent null that would send ensure() back to the prompt.
+ */
+function documentedAbsence(error) {
+    if (exitCodeOf(error) !== KV_NO_VALUE_FOUND)
+        return false;
+    return (error?.stderr ?? '').includes(NO_VALUE_FOUND_MARKER);
+}
+/** The mount name, resolved per call so tests can flip the override freely. */
+function mountName() {
+    return process.env.ENVSEAL_VAULT_MOUNT ?? DEFAULT_MOUNT;
+}
+/**
+ * One server-side path PER KEY, scoped by project the way keychain.ts scopes
+ * its account names: `envseal/<project-leaf>/<key>`. The key must ride in the
+ * path, not sit beside its siblings as a field on a shared path: `vault kv
+ * put` REPLACES the entire data map at the target and `kv delete` removes the
+ * whole path, so shared-path storage would let every write silently destroy
+ * every other key and any single remove destroy them all. Both sinks scope by
+ * the leaf directory name of the project root, so two checkouts of one repo
+ * stay separate unless they share a basename — the same trade keychain makes.
+ */
+function relativePath(paths, key) {
+    const projectId = paths.root.split(/[\\/]/).pop() ?? 'unknown';
+    return `envseal/${projectId}/${key}`;
+}
+/**
+ * Auth posture: the token reaches the CLI through its own discovery chain
+ * (VAULT_TOKEN or ~/.vault-token); this sink never passes -token=, which
+ * would put the credential in argv. Writes need create/update on
+ * `<mount>/envseal/*`; reads need read on the same paths.
+ */
+export class VaultSink extends CliSinkBase {
+    id = 'vault';
+    requiredCommands = ['vault'];
+    unavailableReason() {
+        // A present-but-unaddressed binary (VAULT_ADDR unset) is indistinguishable
+        // from a missing one until an operation runs, so the message names both.
+        return 'the vault CLI is not installed or VAULT_ADDR is unset';
+    }
+    /**
+     * Single choke point for every spawn this sink makes. Production resolves
+     * `vault` off PATH; tests substitute a fake provider here instead of staging
+     * one on PATH, because Windows cannot spawn shebang scripts directly and a
+     * PATH-only double would leave the parsing/error-mapping logic unexercised
+     * there (see vault-sink.test.ts).
+     */
+    run(args, options = {}) {
+        return execCli('vault', [...args], options);
+    }
+    /**
+     * Vault on PATH AND an address to talk to. The base probe deliberately
+     * checks binaries only — VAULT_ADDR-style configuration is validated here
+     * and at operation time, where its absence can produce a precise message.
+     */
+    async available(_paths) {
+        return (await super.available(_paths)) && Boolean(process.env.VAULT_ADDR);
+    }
+    async read(paths, key) {
+        await this.requireReady();
+        try {
+            const { stdout } = await this.run([
+                'kv',
+                'get',
+                '-field',
+                key,
+                '-mount',
+                mountName(),
+                relativePath(paths, key),
+            ]);
+            // -field prints the value plus one trailing newline; strip exactly that
+            // one, byte-exact like keychain.ts — never a blanket trim, which would
+            // corrupt a value that genuinely ends in whitespace. A stored value that
+            // itself ends in a literal newline loses it here, the same trade every
+            // newline-terminated CLI output in this codebase makes.
+            return asSecret(Buffer.from(stdout.replace(/\r?\n$/, ''), 'utf8'));
+        }
+        catch (error) {
+            if (documentedAbsence(error))
+                return null;
+            throw this.sinkFailure('read', error, key);
+        }
+    }
+    async write(paths, key, value) {
+        await this.requireReady();
+        try {
+            // `<KEY>=-` is vault's documented stdin form (`echo x | vault kv put
+            // -mount=secret foo bar=-`): the bytes travel through the inherited
+            // pipe until EOF, never argv where any process listing could read them.
+            // Exactly one field reads stdin per call, so ordering quirks cannot mix
+            // fields. -mount keeps the positional path relative, matching the
+            // documented flag rather than baking the mount into the path string.
+            await this.run(['kv', 'put', '-mount', mountName(), relativePath(paths, key), `${key}=-`], { input: unsafeSecretToUtf8(value) });
+        }
+        catch (error) {
+            throw this.sinkFailure('write', error, key);
+        }
+    }
+    async remove(paths, key) {
+        await this.requireReady();
+        try {
+            // kv delete (soft-deletes the latest version), never kv destroy: the
+            // version history stays intact for audit, matching how the other sinks
+            // treat removal as reversible-at-the-provider rather than shredding.
+            await this.run(['kv', 'delete', '-mount', mountName(), relativePath(paths, key)]);
+            // Current servers report success ("Data deleted (if it existed)...")
+            // even when nothing was ever written, so true reflects what the tool
+            // actually reported; the absence mapping below is defensive for builds
+            // that surface a missing path the way kv get does.
+            return true;
+        }
+        catch (error) {
+            if (documentedAbsence(error))
+                return false;
+            throw this.sinkFailure('remove', error, key);
+        }
+    }
+    /**
+     * Every operation re-probes the CLI — available() may have been consulted
+     * long before, and the binary can vanish in between — then demands
+     * VAULT_ADDR separately, whose absence gets its own precise message instead
+     * of hiding behind the generic reason.
+     */
+    async requireReady() {
+        await this.requirePrerequisites();
+        if (!process.env.VAULT_ADDR) {
+            throw new SepError({
+                code: 'SEP_SINK_UNAVAILABLE',
+                userMessage: `The ${this.id} sink is not available — VAULT_ADDR is unset.`,
+            });
+        }
+    }
+}
+export const vaultSink = new VaultSink();
+//# sourceMappingURL=vault.js.map

package/dist/tickets.d.ts

@@ -0,0 +1,49 @@
+import type { TicketKeyOutcome, TicketOutcome } from '@envseal/protocol';
+export type TicketRecordState = 'pending' | 'resolved' | 'expired' | 'cancelled';
+export interface TicketRecord {
+    ticket: string;
+    nonce: string;
+    keys: string[];
+    reason: string;
+    surface: string;
+    createdAt: number;
+    expiresAt: number;
+    state: TicketRecordState;
+    outcomes: Map<string, TicketKeyOutcome>;
+}
+export interface TicketStoreOptions {
+    ttlMs?: number;
+    sweepIntervalMs?: number;
+}
+export declare class TicketStore {
+    private readonly records;
+    private readonly waiters;
+    private readonly pendingAwaits;
+    private readonly timer;
+    private readonly defaultTtlMs;
+    constructor(options?: TicketStoreOptions);
+    create(opts: {
+        keys: string[];
+        reason: string;
+        surface: string;
+        ttlMs?: number;
+    }): TicketRecord;
+    get(ticket: string): TicketRecord | undefined;
+    setOutcome(ticket: string, key: string, outcome: TicketKeyOutcome): void;
+    resolve(ticket: string): void;
+    cancel(ticket: string): void;
+    sweep(now?: number): void;
+    /**
+     * 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.
+     */
+    private expireIfDue;
+    await(ticket: string, timeoutMs: number): Promise<TicketOutcome>;
+    dispose(): void;
+    private toOutcome;
+    private subscribe;
+    private unsubscribe;
+    private bump;
+}
+//# sourceMappingURL=tickets.d.ts.map