@run402/sdk 4.39.0 → 4.40.0

package/dist/node/gitvault-mirror-config.d.ts

@@ -0,0 +1,53 @@
+import { GitvaultKeystore } from "./gitvault-keystore.js";
+/** Where the mirror writes objects. Directory is a plain local (or network-mounted) path; S3 is `s3://<bucket>/<prefix>`. */
+export type GitvaultMirrorDestination = {
+    kind: "directory";
+    path: string;
+} | {
+    kind: "s3";
+    bucket: string;
+    prefix: string;
+    region: string;
+    endpoint?: string;
+};
+/** How the S3 destination authenticates. Never a raw key — see the module doc. */
+export type GitvaultMirrorCredential = {
+    kind: "profile";
+    profile: string;
+} | {
+    kind: "ambient";
+};
+/** `mirrors/<repo_id>.json` — the ONLY thing this file persists: where, and which named credential to resolve at use time. */
+export interface GitvaultMirrorConfig {
+    version: 1;
+    repo_id: string;
+    destination: GitvaultMirrorDestination;
+    /** Present only for an `s3` destination — a directory destination needs no credential. */
+    credential?: GitvaultMirrorCredential;
+    created_at: string;
+    updated_at: string;
+}
+export declare function mirrorsDir(keystore: GitvaultKeystore): string;
+export declare function mirrorConfigPath(keystore: GitvaultKeystore, repoId: string): string;
+/** Read the mirror config for one vault, or `null` when none is configured. */
+export declare function readMirrorConfig(keystore: GitvaultKeystore, repoId: string): GitvaultMirrorConfig | null;
+/** Every repo id with a mirror configured on this machine. */
+export declare function listMirroredRepoIds(keystore: GitvaultKeystore): string[];
+/** Set (create or replace) the mirror destination for one vault. */
+export declare function saveMirrorConfig(keystore: GitvaultKeystore, input: {
+    repo_id: string;
+    destination: GitvaultMirrorDestination;
+    credential?: GitvaultMirrorCredential;
+}, now?: () => Date): GitvaultMirrorConfig;
+/** Remove the mirror config for one vault. Never touches the mirror's own bytes — this only stops future pushes/syncs from targeting it. */
+export declare function removeMirrorConfig(keystore: GitvaultKeystore, repoId: string): {
+    removed: boolean;
+};
+/** Parse `s3://<bucket>/<prefix>` or a plain filesystem path into a {@link GitvaultMirrorDestination}. */
+export declare function parseMirrorDestinationUrl(url: string, options?: {
+    region?: string;
+    endpoint?: string;
+}): GitvaultMirrorDestination;
+/** Render a destination back to the address form a human typed (for `status`/errors). */
+export declare function formatMirrorDestination(destination: GitvaultMirrorDestination): string;
+//# sourceMappingURL=gitvault-mirror-config.d.ts.map

package/dist/node/gitvault-mirror-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitvault-mirror-config.d.ts","sourceRoot":"","sources":["../../src/node/gitvault-mirror-config.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,gBAAgB,EAAyC,MAAM,wBAAwB,CAAC;AAMjG,6HAA6H;AAC7H,MAAM,MAAM,yBAAyB,GACjC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF,kFAAkF;AAClF,MAAM,MAAM,wBAAwB,GAChC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB,8HAA8H;AAC9H,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,yBAAyB,CAAC;IACvC,0FAA0F;IAC1F,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAE7D;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGnF;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAaxG;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAQxE;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,yBAAyB,CAAC;IAAC,UAAU,CAAC,EAAE,wBAAwB,CAAA;CAAE,EAAE,GAAG,GAAE,MAAM,IAAuB,GAAG,oBAAoB,CAehO;AAED,4IAA4I;AAC5I,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CASnG;AAED,0GAA0G;AAC1G,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,yBAAyB,CAYtI;AAED,yFAAyF;AACzF,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,yBAAyB,GAAG,MAAM,CAEtF"}

package/dist/node/gitvault-mirror-config.js

@@ -0,0 +1,112 @@
+/**
+ * gitvault-mirror-and-recover — mirror destination config (design D1/D2,
+ * task 2.1).
+ *
+ * Per-vault mirror configuration lives BESIDE the keystore, in its own
+ * sibling directory (`<keystore root>/mirrors/<repo_id>.json`) — never in
+ * `run402.config.json` (that file is committed to the repository, and a
+ * mirror destination is a per-machine operational fact, not something to
+ * share with every clone) and never containing a raw secret value. The
+ * credential field names an AWS profile OR selects the ambient environment
+ * chain (`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`/`AWS_SESSION_TOKEN`) —
+ * resolved at USE time by {@link ../node/gitvault-mirror-backend.js}, never
+ * read or cached here. D1 is the reason this file exists at all: run402
+ * never holds a credential to the customer's bucket, so the credential must
+ * live somewhere run402 code never uploads or transmits — this config file,
+ * read only by the client's own machine.
+ */
+import { existsSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { LocalError } from "../errors.js";
+import { GITVAULT_SRC_RE } from "../namespaces/gitvault.crypto.js";
+import { readFileNoFollow, writeFileAtomic0600 } from "./gitvault-keystore.js";
+function fail(code, message, context, details, nextActions) {
+    throw new LocalError(message, context, { code, details, ...(nextActions ? { next_actions: nextActions } : {}) });
+}
+export function mirrorsDir(keystore) {
+    return join(keystore.rootDir, "mirrors");
+}
+export function mirrorConfigPath(keystore, repoId) {
+    if (!GITVAULT_SRC_RE.test(repoId))
+        fail("GITVAULT_BAD_REPO_ID", `not a src_ id: ${repoId}`, "resolving gitvault mirror config path");
+    return join(mirrorsDir(keystore), `${repoId}.json`);
+}
+/** Read the mirror config for one vault, or `null` when none is configured. */
+export function readMirrorConfig(keystore, repoId) {
+    const text = readFileNoFollow(mirrorConfigPath(keystore, repoId));
+    if (!text)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (e) {
+        fail("GITVAULT_MIRROR_CONFIG_CORRUPT", `mirror config for ${repoId} is not valid JSON: ${e.message}`, "reading gitvault mirror config", { repo_id: repoId });
+    }
+    if (parsed.version !== 1 || parsed.repo_id !== repoId || !parsed.destination) {
+        fail("GITVAULT_MIRROR_CONFIG_CORRUPT", `mirror config for ${repoId} is not a version-1 gitvault mirror config`, "reading gitvault mirror config", { repo_id: repoId });
+    }
+    return parsed;
+}
+/** Every repo id with a mirror configured on this machine. */
+export function listMirroredRepoIds(keystore) {
+    const dir = mirrorsDir(keystore);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((n) => n.endsWith(".json"))
+        .map((n) => n.slice(0, -5))
+        .filter((id) => GITVAULT_SRC_RE.test(id))
+        .sort();
+}
+/** Set (create or replace) the mirror destination for one vault. */
+export function saveMirrorConfig(keystore, input, now = () => new Date()) {
+    if (input.destination.kind === "s3" && !input.credential) {
+        fail("GITVAULT_MIRROR_CREDENTIAL_REQUIRED", "an s3 mirror destination needs a credential — pass --profile <name> or --ambient", "configuring gitvault mirror");
+    }
+    const existing = readMirrorConfig(keystore, input.repo_id);
+    const full = {
+        version: 1,
+        repo_id: input.repo_id,
+        destination: input.destination,
+        ...(input.credential ? { credential: input.credential } : {}),
+        created_at: existing?.created_at ?? now().toISOString(),
+        updated_at: now().toISOString(),
+    };
+    writeFileAtomic0600(mirrorConfigPath(keystore, input.repo_id), JSON.stringify(full, null, 2));
+    return full;
+}
+/** Remove the mirror config for one vault. Never touches the mirror's own bytes — this only stops future pushes/syncs from targeting it. */
+export function removeMirrorConfig(keystore, repoId) {
+    const path = mirrorConfigPath(keystore, repoId);
+    if (!existsSync(path))
+        return { removed: false };
+    try {
+        unlinkSync(path);
+    }
+    catch (e) {
+        fail("GITVAULT_MIRROR_CONFIG_REMOVE_FAILED", `could not remove mirror config for ${repoId}: ${e.message}`, "removing gitvault mirror config", { repo_id: repoId });
+    }
+    return { removed: true };
+}
+/** Parse `s3://<bucket>/<prefix>` or a plain filesystem path into a {@link GitvaultMirrorDestination}. */
+export function parseMirrorDestinationUrl(url, options = {}) {
+    if (url.startsWith("s3://")) {
+        const rest = url.slice("s3://".length);
+        const slash = rest.indexOf("/");
+        const bucket = slash === -1 ? rest : rest.slice(0, slash);
+        const prefix = slash === -1 ? "" : rest.slice(slash + 1).replace(/\/+$/, "");
+        if (!bucket)
+            fail("GITVAULT_MIRROR_DESTINATION_INVALID", `${url} names no bucket`, "parsing gitvault mirror destination", { url });
+        const region = options.region ?? process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION;
+        if (!region)
+            fail("GITVAULT_MIRROR_REGION_REQUIRED", `an s3 destination needs a region — pass --region or set AWS_REGION`, "parsing gitvault mirror destination", { url });
+        return { kind: "s3", bucket, prefix, region, ...(options.endpoint ? { endpoint: options.endpoint } : {}) };
+    }
+    return { kind: "directory", path: url };
+}
+/** Render a destination back to the address form a human typed (for `status`/errors). */
+export function formatMirrorDestination(destination) {
+    return destination.kind === "s3" ? `s3://${destination.bucket}/${destination.prefix}` : destination.path;
+}
+//# sourceMappingURL=gitvault-mirror-config.js.map

package/dist/node/gitvault-mirror-config.js.map

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

package/dist/node/gitvault-mirror.d.ts

@@ -0,0 +1,120 @@
+import type { Client } from "../kernel.js";
+import { GITVAULT_MIRROR_KEYSTORE_STILL_REQUIRED_STATEMENT, GITVAULT_MIRROR_VALIDITY_NOT_FRESHNESS_STATEMENT } from "../namespaces/gitvault.crypto.js";
+import { GitvaultKeystore } from "./gitvault-keystore.js";
+import { type GitvaultMirrorBackend } from "./gitvault-mirror-backend.js";
+/**
+ * REPO-RELATIVE — the `source/<repo_id>/` prefix has already been stripped
+ * (see the module doc's mirror-layout mapping). This is the shape every
+ * OTHER function in this module, `gitvault-recover.ts`, and the mirror
+ * backend interface all consume; nothing here ever sees the raw wire key
+ * except `listGitvaultObjectsAll` itself.
+ *
+ * `size_bytes` is an exact decimal string for EVERY kind, including the two
+ * generation-addressed chain kinds (`head`/`vault_genesis` at generation
+ * zero, `admission_record`) — never `null`.
+ */
+export interface GitvaultObjectEntry {
+    key: string;
+    object_kind: string;
+    sha256: string;
+    size_bytes: string;
+}
+/** Page through `GET /gitvault/v1/vaults/:vault_id/objects`, collecting every entry, stripped to repo-relative keys. Store-and-echo cursor per D3a — never parsed here either. */
+export declare function listGitvaultObjectsAll(client: Client, repoId: string): Promise<GitvaultObjectEntry[]>;
+/** Read one object's bytes by key, using the same wire identity every stored kind already carries (§3 layout). `null` when the gateway reports the object absent. */
+export declare function readGitvaultObjectBytes(client: Client, repoId: string, entry: GitvaultObjectEntry): Promise<Uint8Array | null>;
+/** Exported for the key-shape conformance test (`gitvault-mirror-recover.test.ts`) — never called for its own sake outside this module. */
+export declare function generationRouteForKey(key: string): {
+    route: "heads" | "admissions";
+    generation: string;
+} | null;
+/**
+ * `key_envelope` is path-addressed by `(epoch, recipient_fingerprint)`, not a
+ * plain object_id — every other kind uses its object_id, read straight from
+ * the key's own filename via an ANCHORED, kind-specific pattern (never a
+ * loose, unanchored fallback — see {@link NON_GENERATION_KEY_SPECS}).
+ * Exported for the key-shape conformance test.
+ */
+export declare function objectReadRequestForEntry(entry: GitvaultObjectEntry): {
+    object_kind: string;
+    object_id?: string;
+    epoch?: string;
+    recipient_fingerprint?: string;
+};
+export interface GitvaultMirrorWritePlan {
+    /** Every non-head, non-admission entry, in listing order — write these FIRST, in any order among themselves. */
+    objects: GitvaultObjectEntry[];
+    /** Then admission records and heads, interleaved, strictly ascending by generation (admission before its own head). */
+    admissionsAndHeads: GitvaultObjectEntry[];
+}
+/** Sort a flat listing into the admission-order write plan (module doc above). */
+export declare function planMirrorWrite(entries: readonly GitvaultObjectEntry[]): GitvaultMirrorWritePlan;
+export interface GitvaultMirrorCopyResult {
+    key: string;
+    outcome: "copied" | "already_present" | "skipped_foreign_recipient" | "failed";
+    size_bytes?: string;
+    error?: string;
+}
+export interface GitvaultMirrorSyncSummary {
+    repo_id: string;
+    destination: string;
+    /** Faithful counts of what ACTUALLY happened this call — never an estimate (design D3a rider (e)). */
+    objects_listed: number;
+    objects_copied: number;
+    objects_already_present: number;
+    /**
+     * Task 5.3 follow-up: a `key_envelope` wrapped for a DIFFERENT recipient
+     * than this machine's own identity — EXPECTED, not a problem. The
+     * recipient-only read gate means a mirror can only ever hold envelopes
+     * addressed to the local identity; a multi-recipient vault
+     * (gitvault-human-envelopes) makes this the norm. Never counted toward
+     * `objects_failed`, and never causes `mirror sync` to report anything but
+     * success — named per-key in `skipped_foreign_recipient_keys` so a reader
+     * can tell "expected skip" from "silent gap" without cross-referencing.
+     */
+    objects_skipped_foreign_recipient: number;
+    skipped_foreign_recipient_keys: string[];
+    objects_failed: number;
+    bytes_copied: string;
+    errors: Array<{
+        key: string;
+        error: string;
+    }>;
+    validity_not_freshness: typeof GITVAULT_MIRROR_VALIDITY_NOT_FRESHNESS_STATEMENT;
+    keystore_still_required: typeof GITVAULT_MIRROR_KEYSTORE_STILL_REQUIRED_STATEMENT;
+}
+export interface GitvaultMirrorSyncOptions {
+    keystore?: GitvaultKeystore;
+    /** Test/advanced hook: an already-opened backend, bypassing config resolution. */
+    backend?: GitvaultMirrorBackend;
+}
+/**
+ * `run402 gitvault mirror sync` (task 2.3): list the vault's stored objects,
+ * diff against the mirror by key+size, fetch and hash-verify what's missing,
+ * write it in admission order. Resumable and idempotent — running it twice in
+ * a row with nothing new copies nothing the second time.
+ */
+export declare function mirrorSync(client: Client, repoId: string, options?: GitvaultMirrorSyncOptions): Promise<GitvaultMirrorSyncSummary>;
+export interface GitvaultMirrorPushResult {
+    attempted: boolean;
+    outcome: "pushed" | "skipped_no_mirror" | "failed";
+    summary?: GitvaultMirrorSyncSummary;
+    error?: string;
+}
+/**
+ * Fires after an ordinary vault push/deploy produces a new generation. NEVER
+ * throws and NEVER alters the caller's deploy/push outcome (design D6) — a
+ * mirror is strictly extra durability, and its failure is reported BESIDE the
+ * vault result as a distinct line, not folded into it. Fires only when a
+ * mirror is configured for this vault; a vault with no mirror gets
+ * `skipped_no_mirror` (not an error) so callers can log it uniformly without
+ * branching on whether mirroring was ever opted into.
+ *
+ * Implemented as a full (but INCREMENTAL, idempotent) sync rather than a
+ * push-scoped upload: the objects listing + diff-by-size machinery already
+ * makes an all-caught-up sync cheap (one listing page, zero copies), and this
+ * keeps the admission-order write discipline in exactly one place instead of
+ * a second, push-scoped code path that could drift from it.
+ */
+export declare function mirrorPushForGeneration(client: Client, repoId: string, options?: GitvaultMirrorSyncOptions): Promise<GitvaultMirrorPushResult>;
+//# sourceMappingURL=gitvault-mirror.d.ts.map

package/dist/node/gitvault-mirror.d.ts.map

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