run402 4.24.0 → 4.25.0

package/sdk/dist/node/gitvault-keystore.d.ts

@@ -0,0 +1,207 @@
+/**
+ * gitvault — the principal keystore (protocol rev 40 §5.1; task 5.2).
+ *
+ * Layout (under the active profile's config dir, beside the project-key cache
+ * `core/src/keystore.ts` manages — `RUN402_CONFIG_DIR` / `RUN402_WALLET` aware):
+ *
+ *   <config>/gitvault/
+ *     identity.json                 Ed25519 seed + X25519 private key (0600)
+ *     repos/<repo_id>.json          K_repo, trust pin, dual pins, last ref transaction (0600)
+ *     repos/<repo_id>.lock/         per-repo lock (mkdir-atomic, 0700)
+ *     receipts/<repo_id>.recovery_receipt.json   the recovery receipt (NOT a secret; more copies better)
+ *     journal/<client_creation_id>.json          six-stage creation journals (task 5.3)
+ *     audit.log                     append-only JSON lines (0600)
+ *
+ * Discipline (spec: "Writes SHALL be atomic with per-repo locks, no-follow
+ * creation, and permission audits"): directories 0700, files 0600, every
+ * write = temp file (O_NOFOLLOW|O_EXCL) + fsync + rename + directory fsync,
+ * and `auditKeystorePermissions()` runs at open so a world-readable identity
+ * is a named finding, never silent.
+ *
+ * Transitions (protocol §5.1 partial-loss table) are DERIVED by
+ * {@link GitvaultKeystore.assess} and acted on by explicit methods — the
+ * keystore never guesses:
+ *   - repo file lost + identity intact  → `restoreRepoFromEnvelope` (own envelope)
+ *   - signing key lost, K_repo held     → `read_only` (clear report)
+ *   - stale pin                         → `stale_pin` (re-verify from genesis; 5.4)
+ *   - whole keystore lost               → `VAULT_UNRECOVERABLE` (§0, verbatim)
+ */
+import type { GitvaultEncryptionKeypair, GitvaultKeyEnvelope, GitvaultRecoveryReceipt, GitvaultSigningKeypair, GitvaultVaultGenesis } from "../namespaces/gitvault.types.js";
+/** `identity.json` — the principal's two private keys. Either half MAY be absent after partial loss. */
+export interface GitvaultIdentityFile {
+    version: 1;
+    /** Ed25519 32-byte seed, lowercase hex. Absent ⇒ the signing key is lost (read-only principal). */
+    signing_seed_hex?: string;
+    /** Raw Ed25519 public key, base64url. */
+    signing_pubkey: string;
+    /** `vk_` fingerprint. */
+    signing_fingerprint: string;
+    /** X25519 32-byte private key, lowercase hex. Absent ⇒ no envelope can be opened. */
+    encryption_private_key_hex?: string;
+    /** Raw X25519 public key, base64url. */
+    encryption_pubkey: string;
+    /** `ek_` fingerprint. */
+    encryption_fingerprint: string;
+    created_at: string;
+}
+/** The dual pins (protocol §6.4): the newest authenticated head and its generation. */
+export interface GitvaultHeadPin {
+    generation: string;
+    head_sha256: string;
+    pinned_at: string;
+}
+/** `repos/<repo_id>.json` — everything per-vault the principal must not lose. */
+export interface GitvaultRepoFile {
+    version: 1;
+    repo_id: string;
+    org_id: string;
+    project_id: string;
+    /** Raw 32-byte K_repo, lowercase hex. */
+    k_repo_hex: string;
+    /** The current epoch (V0: always `0000000000000001`). */
+    epoch: string;
+    /** Trust pin: the admitted genesis stored-bytes hash. */
+    genesis_sha256: string;
+    /** `highest_authenticated` (§6.4): chain-verified; a listing below it is `GENERATION_REGRESSION`. `null` until the first head is authenticated. */
+    head_pin: GitvaultHeadPin | null;
+    /** `highest_materialized` (§6.4): decrypted + applied — the ONLY push base. Absent/`null` ⇒ never materialized. */
+    materialized_pin?: GitvaultHeadPin | null;
+    /** The verified-prefix watermark of a budget-interrupted verification (§9.3 — resumable). Absent/`null` when none is pending. */
+    verified_prefix?: GitvaultHeadPin | null;
+    /** The last ref transaction this principal published (5.4 fills it). */
+    last_ref_transaction: Record<string, unknown> | null;
+    /** How this file came to exist — creation, or a §5.1 restore from the principal's own envelope. */
+    provenance: "created" | "restored_from_envelope";
+    updated_at: string;
+}
+/** One `audit.log` line. */
+export interface GitvaultAuditEntry {
+    at: string;
+    event: GitvaultAuditEvent;
+    repo_id?: string;
+    details?: Record<string, unknown>;
+}
+export type GitvaultAuditEvent = "keystore_opened" | "identity_created" | "repo_saved" | "repo_restored_from_envelope" | "recovery_receipt_stored" | "permission_finding" | "lock_acquired" | "lock_released" | "lock_stale_reclaimed" | "transition_assessed" | "journal_stage";
+/** A permission-audit finding (never fatal by default; surfaced to doctor). */
+export interface GitvaultPermissionFinding {
+    path: string;
+    problem: "world_or_group_accessible" | "symlink" | "not_owned_by_user" | "missing";
+    mode?: string;
+}
+/** The §5.1 partial-loss transition the keystore is in for one vault. */
+export type GitvaultKeystoreState = {
+    state: "ready";
+    repo: GitvaultRepoFile;
+} | {
+    state: "repo_state_lost_identity_intact";
+    next_action: "restore_from_envelope";
+} | {
+    state: "read_only";
+    repo: GitvaultRepoFile;
+    reason: "signing_key_lost";
+} | {
+    state: "stale_pin";
+    repo: GitvaultRepoFile;
+    next_action: "reverify_from_genesis";
+} | {
+    state: "unrecoverable";
+    code: "VAULT_UNRECOVERABLE";
+    statement: string;
+    doctor_text: string;
+};
+export interface GitvaultKeystoreOptions {
+    /** Override the keystore root (tests). Defaults to `<config dir>/gitvault`. */
+    rootDir?: string;
+    /** Clock injection (tests). */
+    now?: () => Date;
+    /** When true, a permission finding on open throws `GITVAULT_KEYSTORE_PERMISSIONS` instead of only auditing. */
+    strictPermissions?: boolean;
+}
+export interface GitvaultLockOptions {
+    /** How long a lock is considered live before it is reclaimed as stale (ms). Default 10 min. */
+    staleAfterMs?: number;
+    /** Total wait budget before `GITVAULT_KEYSTORE_LOCKED` (ms). Default 30 s. */
+    timeoutMs?: number;
+}
+/** Default keystore root: `<active profile config dir>/gitvault`. */
+export declare function getGitvaultKeystoreRoot(): string;
+/**
+ * Atomic, no-follow, fsynced write: `O_WRONLY|O_CREAT|O_EXCL|O_NOFOLLOW` on a
+ * temp sibling, fsync, rename over the target, fsync the directory.
+ */
+export declare function writeFileAtomic0600(path: string, text: string): void;
+/** No-follow read: a symlinked keystore file is a refusal, not a read. */
+export declare function readFileNoFollow(path: string): string | null;
+export declare class GitvaultKeystore {
+    readonly rootDir: string;
+    private readonly now;
+    private readonly strictPermissions;
+    constructor(options?: GitvaultKeystoreOptions);
+    /** Open (creating the directory skeleton) and run the permission audit. */
+    static open(options?: GitvaultKeystoreOptions): GitvaultKeystore;
+    get identityPath(): string;
+    get reposDir(): string;
+    get receiptsDir(): string;
+    get journalDir(): string;
+    get auditLogPath(): string;
+    repoPath(repoId: string): string;
+    recoveryReceiptPath(repoId: string): string;
+    /** Audit every keystore path that exists; findings are recorded in `audit.log` and returned. */
+    auditPermissions(): GitvaultPermissionFinding[];
+    /** Append one JSON line to `audit.log` (0600, created no-follow). */
+    audit(event: GitvaultAuditEvent, repoId?: string, details?: Record<string, unknown>): void;
+    /** Read the audit log (newest last). */
+    readAuditLog(): GitvaultAuditEntry[];
+    readIdentity(): GitvaultIdentityFile | null;
+    /** Create the identity if absent; never overwrites an existing one. */
+    ensureIdentity(): GitvaultIdentityFile;
+    /** The signing keypair, or `null` when the signing seed is lost (read-only principal). */
+    signingKeypair(identity?: GitvaultIdentityFile): GitvaultSigningKeypair | null;
+    /** The encryption keypair, or `null` when the X25519 private key is lost. */
+    encryptionKeypair(identity?: GitvaultIdentityFile): GitvaultEncryptionKeypair | null;
+    private requireIdentity;
+    readRepo(repoId: string): GitvaultRepoFile | null;
+    listRepoIds(): string[];
+    /** Save (create or replace) a repo file under the per-repo lock. */
+    saveRepo(repo: Omit<GitvaultRepoFile, "version" | "updated_at">): GitvaultRepoFile;
+    /** Update the dual pins / last ref transaction without touching key material. */
+    updateRepo(repoId: string, patch: Partial<Pick<GitvaultRepoFile, "head_pin" | "materialized_pin" | "verified_prefix" | "last_ref_transaction" | "epoch">>): GitvaultRepoFile;
+    saveRecoveryReceipt(receipt: GitvaultRecoveryReceipt): void;
+    readRecoveryReceipt(repoId: string): GitvaultRecoveryReceipt | null;
+    /**
+     * Run `fn` holding the per-repo lock (`repos/<repo_id>.lock/`, mkdir-atomic).
+     * A lock older than `staleAfterMs` whose recorded pid is dead is reclaimed
+     * (audited). Re-entrant for the same process+repo.
+     */
+    withRepoLock<T>(repoId: string, fn: () => T, options?: GitvaultLockOptions): T;
+    private readonly held;
+    private reclaimStaleLock;
+    /**
+     * Derive the partial-loss transition for one vault. `expectedGenesisSha256`
+     * (from a freshly listed genesis, 5.4) turns a pin mismatch into `stale_pin`.
+     */
+    assess(repoId: string, expectedGenesisSha256?: string): GitvaultKeystoreState;
+    /**
+     * §5.1 "repo file lost + identity intact → restore K_repo from own envelope".
+     * The genesis is checked (signature + key bindings against the stored
+     * envelope + the recovery receipt/pin when one survives) BEFORE the envelope
+     * is opened; the restored file is marked `restored_from_envelope`.
+     */
+    restoreRepoFromEnvelope(input: {
+        genesis: GitvaultVaultGenesis;
+        envelope: GitvaultKeyEnvelope;
+        /** A surviving receipt (on disk or supplied) authenticates the genesis; without one the restore is labeled unauthenticated salvage. */
+        recovery_receipt?: GitvaultRecoveryReceipt | null;
+    }): Promise<{
+        repo: GitvaultRepoFile;
+        trust: "receipt" | "unauthenticated_salvage";
+    }>;
+    /** Identity fingerprints for display/doctor (never key material). */
+    identitySummary(): {
+        signing_fingerprint: string;
+        encryption_fingerprint: string;
+        signing_key_present: boolean;
+        encryption_key_present: boolean;
+    } | null;
+}
+//# sourceMappingURL=gitvault-keystore.d.ts.map

package/sdk/dist/node/gitvault-keystore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitvault-keystore.d.ts","sourceRoot":"","sources":["../../src/node/gitvault-keystore.ts"],"names":[],"mappings":"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"}