sealkeep 0.9.0 → 0.11.0

package/dist/src/recovery-codes.d.ts

@@ -0,0 +1,32 @@
+import { type EscrowBlob } from "./cloud.js";
+import type { BackendName } from "./secrets.js";
+export declare const RECOVERY_CODE_COUNT = 5;
+export declare const RECOVERY_KIT_AGENT = "sealkeep-recovery-kit";
+export declare const RECOVERY_KIT_VERSION = 1;
+export type RecoveryKitStatus = {
+    available: boolean;
+    remaining: number;
+    createdAt: string | null;
+};
+export type RecoveryKitCreated = RecoveryKitStatus & {
+    codes: string[];
+};
+export declare function generateRecoveryCode(): string;
+/** Normalization is deliberately strict enough to catch transcription mistakes. */
+export declare function canonicalRecoveryCode(value: string): string;
+export declare function recoveryKitStatusFromBlob(blob: EscrowBlob | null): RecoveryKitStatus;
+export declare function recoveryKitStatus(dataDir: string, preferred?: BackendName): Promise<RecoveryKitStatus>;
+/**
+ * Generates a replacement set. Codes are returned once and never persisted in
+ * plaintext; only independent scrypt+AEAD wraps enter the escrow envelope.
+ */
+export declare function createRecoveryCodes(dataDir: string, rawPhrase: string, preferred?: BackendName, count?: number): Promise<RecoveryKitCreated>;
+/**
+ * Restores the original vault on a Gmail-authorized fresh machine. Cloud first
+ * awards one opaque capsule to one random claim; only the winner receives a
+ * code-decryptable key wrap. Response-loss retries reuse the durable claim id.
+ */
+export declare function recoverWithRecoveryCode(dataDir: string, rawCode: string, preferred?: BackendName): Promise<{
+    vaultId: string;
+    remaining: number;
+}>;

package/dist/src/recovery-codes.js

@@ -0,0 +1,338 @@
+import { createHash, randomBytes } from "node:crypto";
+import { decryptArchive, encryptArchive, } from "../packages/sealkeep-crypto/src/index.js";
+import { cloudRecoveryKitStatus, claimCloudRecoveryCodeCapsule, cloudToken, consumeCloudRecoveryCode, redeemCloudRecoveryCode, replaceCloudRecoveryKit, } from "./cloud.js";
+import { adoptPersonalVaultMaterial, assertFreshPersonalVaultTarget } from "./device-enrollment.js";
+import { fail, isSealkeepError } from "./errors.js";
+import { canonicalPhrase } from "./mnemonic.js";
+import { readConfig } from "./vault.js";
+import { equalHex, phraseCheck } from "./crypto.js";
+import { chooseBackend, rememberRecoveryPhrase, resolveRecoveryPhrase } from "./secrets.js";
+const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const CODE_BYTES = 16;
+const CLAIM_BYTES = 16;
+const CLAIM_SERVICE = "sealkeep-recovery-claim";
+export const RECOVERY_CODE_COUNT = 5;
+export const RECOVERY_KIT_AGENT = "sealkeep-recovery-kit";
+export const RECOVERY_KIT_VERSION = 1;
+/** Crockford Base32: case-insensitive and omits the easiest-to-confuse letters. */
+function base32(input) {
+    let bits = 0;
+    let value = 0;
+    let output = "";
+    for (const byte of input) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            output += ALPHABET[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    if (bits > 0)
+        output += ALPHABET[(value << (5 - bits)) & 31];
+    return output;
+}
+export function generateRecoveryCode() {
+    const body = base32(randomBytes(CODE_BYTES));
+    return `SK-${body.match(/.{1,4}/g).join("-")}`;
+}
+/** Normalization is deliberately strict enough to catch transcription mistakes. */
+export function canonicalRecoveryCode(value) {
+    const compact = value.trim().toUpperCase().replace(/[\s-]+/g, "");
+    const body = compact.startsWith("SK") ? compact.slice(2) : compact;
+    if (!/^[0-9A-HJKMNP-TV-Z]{26}$/.test(body)) {
+        fail("invalid_argument", "That is not a SealKeep backup code. Enter all 26 characters from the Recovery Kit.");
+    }
+    return `SK-${body.match(/.{1,4}/g).join("-")}`;
+}
+function material(config, phrase) {
+    return {
+        kind: "sealkeep-recovery-kit",
+        version: RECOVERY_KIT_VERSION,
+        vaultId: config.vaultId,
+        recoveryPhrase: canonicalPhrase(phrase),
+        storageMode: config.storageMode === "plain" ? "plain" : "sealed",
+        ...(config.recipients?.length ? { recipients: config.recipients } : {}),
+        ...(config.remoteNaming ? { remoteNaming: config.remoteNaming } : {}),
+        createdAt: new Date().toISOString(),
+    };
+}
+function isRecoveryKit(envelope) {
+    return envelope.manifest.adapter?.agent === RECOVERY_KIT_AGENT
+        && envelope.manifest.adapter?.version === String(RECOVERY_KIT_VERSION);
+}
+function envelopeFrom(blob) {
+    return typeof blob.envelope === "string" ? JSON.parse(blob.envelope) : blob.envelope;
+}
+export function recoveryKitStatusFromBlob(blob) {
+    if (!blob)
+        return { available: false, remaining: 0, createdAt: null };
+    const envelope = envelopeFrom(blob);
+    if (!isRecoveryKit(envelope))
+        return { available: false, remaining: 0, createdAt: blob.created_at ?? null };
+    // Compatibility inspection for pre-capsule kits only. Current kits expose
+    // just the permanent phrase wrap here; authoritative one-time-code status is
+    // account scoped and comes from cloudRecoveryKitStatus().
+    const remaining = Math.max(0, envelope.wrappedKeys.filter((item) => item.type === "phrase").length - 1);
+    return { available: remaining > 0, remaining, createdAt: blob.created_at ?? envelope.manifest.createdAt ?? null };
+}
+export async function recoveryKitStatus(dataDir, preferred) {
+    const status = await cloudRecoveryKitStatus(dataDir, preferred);
+    return { available: status.available, remaining: status.remaining, createdAt: status.created_at ?? null };
+}
+function recoveryCodeRecipientId(rawCode) {
+    return createHash("sha256").update(canonicalRecoveryCode(rawCode)).digest("hex").slice(0, 32);
+}
+/**
+ * Generates a replacement set. Codes are returned once and never persisted in
+ * plaintext; only independent scrypt+AEAD wraps enter the escrow envelope.
+ */
+export async function createRecoveryCodes(dataDir, rawPhrase, preferred, count = RECOVERY_CODE_COUNT) {
+    if (count !== RECOVERY_CODE_COUNT)
+        fail("invalid_argument", `A Recovery Kit contains exactly ${RECOVERY_CODE_COUNT} backup codes`);
+    const config = await readConfig(dataDir);
+    const phrase = canonicalPhrase(rawPhrase);
+    const codes = Array.from({ length: count }, generateRecoveryCode);
+    const recipients = [
+        { kind: "phrase", phrase },
+        ...codes.map((code) => ({ kind: "phrase", phrase: code })),
+    ];
+    const sealed = encryptArchive(Buffer.from(JSON.stringify(material(config, phrase))), {
+        recipients,
+        adapter: { agent: RECOVERY_KIT_AGENT, version: String(RECOVERY_KIT_VERSION) },
+    });
+    const [masterWrap, ...codeWraps] = sealed.envelope.wrappedKeys;
+    if (!masterWrap || codeWraps.length !== codes.length)
+        fail("internal", "The Recovery Kit could not be split into encrypted capsules");
+    const masterEnvelope = { ...sealed.envelope, wrappedKeys: [masterWrap] };
+    const capsules = codeWraps.map((wrappedKey, index) => ({
+        recipient_id: recoveryCodeRecipientId(codes[index]),
+        envelope: { ...sealed.envelope, wrappedKeys: [wrappedKey] },
+        sealed: sealed.ciphertext.toString("base64"),
+    }));
+    const stored = await replaceCloudRecoveryKit(dataDir, { envelope: masterEnvelope, ciphertext: sealed.ciphertext }, capsules, preferred);
+    return { available: true, remaining: stored.remaining, createdAt: stored.created_at ?? sealed.envelope.manifest.createdAt, codes };
+}
+function openWithCode(blob, rawCode) {
+    const code = canonicalRecoveryCode(rawCode);
+    const envelope = envelopeFrom(blob);
+    if (!isRecoveryKit(envelope)) {
+        return fail("archive_not_found", "This account has no Backup Code Recovery Kit yet. Use the 24-word phrase or approve this machine from another device.");
+    }
+    const ciphertext = Buffer.from(blob.sealed, "base64");
+    if (envelope.wrappedKeys.length !== 1 || envelope.wrappedKeys[0]?.type !== "phrase") {
+        return fail("internal", "The Recovery Kit capsule stored for this account is malformed");
+    }
+    let plaintext;
+    try {
+        plaintext = decryptArchive(envelope, ciphertext, { phrase: code });
+    }
+    catch {
+        return fail("recovery_phrase_mismatch", "That backup code is not unused in this Recovery Kit. Check the code or use another one.");
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(plaintext.toString("utf8"));
+    }
+    catch {
+        return fail("internal", "The Recovery Kit stored for this account is malformed");
+    }
+    if (decoded.kind !== "sealkeep-recovery-kit" || decoded.version !== RECOVERY_KIT_VERSION
+        || typeof decoded.vaultId !== "string" || typeof decoded.recoveryPhrase !== "string") {
+        return fail("internal", "The Recovery Kit stored for this account is malformed");
+    }
+    return decoded;
+}
+function pendingClaimRef(rawCode) {
+    const code = canonicalRecoveryCode(rawCode);
+    return { service: CLAIM_SERVICE, account: createHash("sha256").update(code).digest("hex") };
+}
+function parsePendingClaim(raw) {
+    if (!raw)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        if (![1, 2].includes(Number(value.version)) || !/^[a-f0-9]{32}$/.test(String(value.claimId))
+            || !/^[a-f0-9]{32}$/.test(String(value.recipientId)))
+            return null;
+        if (value.version === 1)
+            return {
+                version: 2,
+                claimId: String(value.claimId),
+                recipientId: String(value.recipientId),
+                phase: "claimed",
+            };
+        if (value.phase !== "claimed" && value.phase !== "stored")
+            return null;
+        if (value.phase === "stored" && (typeof value.vaultId !== "string" || !Number.isSafeInteger(value.remaining)))
+            return null;
+        return {
+            version: 2,
+            claimId: String(value.claimId),
+            recipientId: String(value.recipientId),
+            phase: value.phase,
+            ...(typeof value.vaultId === "string" ? { vaultId: value.vaultId } : {}),
+            ...(typeof value.remaining === "number" ? { remaining: value.remaining } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isRecoveryCodeConflict(error) {
+    return isSealkeepError(error) && error.code === "lease_expired";
+}
+/** Only a redeem response can establish that this account has no such capsule.
+ * Do not reinterpret authentication failures, outages, or claim-status misses
+ * as a bad code: those have different retry and recovery semantics. */
+function throwUnavailableRedeem(error) {
+    if (isSealkeepError(error) && error.code === "internal" && error.details.httpStatus === 404) {
+        return fail("recovery_phrase_mismatch", "That backup code is unavailable for this account or already used. Sign in to the account that created the Recovery Kit, or try another code.");
+    }
+    return throwRecoveryCodeConflict(error);
+}
+function isUnavailableRedeem(error) {
+    return isRecoveryCodeConflict(error)
+        || (isSealkeepError(error) && error.code === "internal" && error.details.httpStatus === 404);
+}
+function throwRecoveryCodeConflict(error) {
+    // Cloud maps an unavailable/used recovery recipient to lease_expired. Do
+    // not expose that implementation detail: the setup UI can safely offer the
+    // next printed code, while auth/network errors retain their real meaning.
+    if (isRecoveryCodeConflict(error)) {
+        return fail("recovery_phrase_mismatch", "That backup code is unavailable or already used. Try another code from this Recovery Kit.");
+    }
+    throw error;
+}
+async function consumeClaim(dataDir, pending, preferred) {
+    try {
+        await consumeCloudRecoveryCode(dataDir, pending.recipientId, pending.claimId, preferred);
+    }
+    catch (consumeError) {
+        // A lost consume response is safe to resolve only through the exact random
+        // claim. A 404 means the server did not spend it; retain the phase marker
+        // so a later retry can submit consume again.
+        try {
+            await claimCloudRecoveryCodeCapsule(dataDir, pending.recipientId, pending.claimId, preferred);
+        }
+        catch {
+            throwRecoveryCodeConflict(consumeError);
+        }
+    }
+}
+/**
+ * Restores the original vault on a Gmail-authorized fresh machine. Cloud first
+ * awards one opaque capsule to one random claim; only the winner receives a
+ * code-decryptable key wrap. Response-loss retries reuse the durable claim id.
+ */
+export async function recoverWithRecoveryCode(dataDir, rawCode, preferred) {
+    // An existing config is a recovery of this vault, not device enrollment.
+    // Check the local keystore/environment before creating a durable claim so a
+    // repeated click cannot spend a code when this machine is already unlocked.
+    const current = await readConfig(dataDir).catch((error) => {
+        if (isSealkeepError(error) && error.code === "vault_not_initialized")
+            return null;
+        throw error;
+    });
+    const held = current
+        ? await resolveRecoveryPhrase(dataDir, current.vaultId, undefined, process.env, preferred)
+        : null;
+    const heldForVault = current && held !== null && (() => {
+        try {
+            return equalHex(current.recovery.phraseCheck, phraseCheck(canonicalPhrase(held)));
+        }
+        catch {
+            return false;
+        }
+    })();
+    const ref = pendingClaimRef(rawCode);
+    const backend = await chooseBackend(dataDir, preferred);
+    let pending = parsePendingClaim(await backend.get(ref));
+    if (current) {
+        if (pending?.phase === "stored") {
+            if (pending.vaultId !== current.vaultId) {
+                fail("recovery_phrase_mismatch", "The pending recovery belongs to a different vault. Nothing was changed.");
+            }
+            if (!heldForVault) {
+                fail("recovery_phrase_missing", "This machine stored the recovered phrase but it is no longer available. Restore the machine keystore, then retry.");
+            }
+            await cloudToken(dataDir, preferred);
+            await consumeClaim(dataDir, pending, preferred);
+            await backend.delete(ref).catch(() => undefined);
+            return { vaultId: current.vaultId, remaining: pending.remaining };
+        }
+        if (heldForVault) {
+            fail("invalid_argument", "This vault is already unlocked on this machine. Nothing was changed.");
+        }
+        await cloudToken(dataDir, preferred);
+    }
+    if (!pending) {
+        pending = {
+            version: 2,
+            claimId: randomBytes(CLAIM_BYTES).toString("hex"),
+            recipientId: recoveryCodeRecipientId(rawCode),
+            phase: "claimed",
+        };
+        // This contains only opaque identifiers, never the code, phrase, key wrap,
+        // or decrypted payload. It is enough to retry one ambiguous network result.
+        await backend.set(ref, JSON.stringify(pending));
+    }
+    if (!current)
+        await assertFreshPersonalVaultTarget(dataDir, preferred);
+    let awarded;
+    try {
+        awarded = await redeemCloudRecoveryCode(dataDir, pending.recipientId, pending.claimId, preferred);
+    }
+    catch (redeemError) {
+        // A definitive missing/conflicting capsule was not awarded to this claim.
+        // Retrying cannot turn it into an available code, and must not expose a
+        // generic internal error for the normal wrong-account/wrong-code case.
+        if (isUnavailableRedeem(redeemError)) {
+            await backend.delete(ref).catch(() => undefined);
+            throwUnavailableRedeem(redeemError);
+        }
+        // Redeem is idempotent for the same claim, so a lost response is resolved
+        // by repeating that exact reservation. Claim status is deliberately not
+        // used here: it is the post-consume receipt, and using the same read for
+        // both phases would make it incapable of proving final consumption.
+        try {
+            awarded = await redeemCloudRecoveryCode(dataDir, pending.recipientId, pending.claimId, preferred);
+        }
+        catch {
+            throwUnavailableRedeem(redeemError);
+        }
+    }
+    const payload = openWithCode(awarded, rawCode);
+    if (current) {
+        // Re-read identity after the network round trip. A concurrent replacement
+        // must not cause a phrase for the old vault to be stored under the new one.
+        const latest = await readConfig(dataDir);
+        let recoveredPhrase;
+        try {
+            recoveredPhrase = canonicalPhrase(payload.recoveryPhrase);
+        }
+        catch {
+            fail("recovery_phrase_mismatch", "That backup code does not open this vault. Nothing was changed locally.");
+        }
+        if (latest.vaultId !== current.vaultId || payload.vaultId !== latest.vaultId
+            || !equalHex(latest.recovery.phraseCheck, phraseCheck(recoveredPhrase))) {
+            fail("recovery_phrase_mismatch", "That backup code does not open this vault. Nothing was changed locally.");
+        }
+        // Existing archives/configuration remain untouched; only the convenience
+        // copy in this machine's selected secret backend is restored.
+        await rememberRecoveryPhrase(dataDir, latest.vaultId, recoveredPhrase, preferred);
+        pending = { ...pending, version: 2, phase: "stored", vaultId: latest.vaultId, remaining: awarded.remaining };
+        await backend.set(ref, JSON.stringify(pending));
+        await consumeClaim(dataDir, pending, preferred);
+        await backend.delete(ref).catch(() => undefined);
+        return { vaultId: latest.vaultId, remaining: awarded.remaining };
+    }
+    await adoptPersonalVaultMaterial(dataDir, payload, preferred);
+    pending = { ...pending, version: 2, phase: "stored", vaultId: payload.vaultId, remaining: awarded.remaining };
+    await backend.set(ref, JSON.stringify(pending));
+    await consumeClaim(dataDir, pending, preferred);
+    await backend.delete(ref).catch(() => undefined);
+    return {
+        vaultId: payload.vaultId,
+        remaining: awarded.remaining,
+    };
+}

package/dist/src/recovery.js

@@ -2,6 +2,7 @@ import { createInterface } from "node:readline/promises";
 import { matchesPhraseCheck } from "./crypto.js";
 import { canonicalPhrase, inspectPhrase, isMnemonic, PHRASE_WORDS } from "./mnemonic.js";
 import { readConfig } from "./vault.js";
+import { providerLabel } from "./branding.js";
 /**
  * The recovery kit.
  *
@@ -20,6 +21,8 @@ import { readConfig } from "./vault.js";
  */
 export function recoveryKit(config, options = {}) {
     const when = (options.now ?? new Date()).toISOString().slice(0, 10);
+    const ownStorage = config.remoteStorage?.provider === "vaultline" ? null : config.remoteStorage;
+    const managedStorage = Boolean(options.managed || config.remoteStorage?.provider === "vaultline");
     const blanks = Array.from({ length: PHRASE_WORDS }, (_, index) => `  ${String(index + 1).padStart(2, " ")}. ______________`);
     // Column-major, `rows` apart — the same layout the on-screen grid uses. The
     // offsets were once +6/+12, hard-wired for a 12-word phrase; at 24 words that
@@ -31,15 +34,15 @@ export function recoveryKit(config, options = {}) {
     for (let row = 0; row < rows; row += 1) {
         columns.push([blanks[row], blanks[row + rows], blanks[row + rows * 2]].filter(Boolean).join("   "));
     }
-    return `VAULTLINE RECOVERY KIT
+    return `SEALKEEP RECOVERY KIT
 ${"=".repeat(58)}
 
 Vault        ${config.vaultId}
 Created      ${when}
-Storage      ${config.remoteStorage
-        ? `${config.remoteStorage.provider}://${config.remoteStorage.bucket}/${config.remoteStorage.prefix}`
-        : options.managed
-            ? `Sealkeep Cloud, account ${options.managed.email}`
+Storage      ${ownStorage
+        ? `${providerLabel(ownStorage.provider)} · ${ownStorage.bucket}/${ownStorage.prefix}`
+        : managedStorage
+            ? `Sealkeep Cloud${options.managed?.email ? `, account ${options.managed.email}` : ""}`
             : "this machine only"}
 Devices      ${(config.recipients ?? []).length} registered key(s) besides the phrase
 ${config.storageMode === "plain" ? `
@@ -61,11 +64,11 @@ TO RESTORE ON A NEW MACHINE
 ${"-".repeat(58)}
   1. Install Sealkeep.
   2. Run:  sealkeep setup --recovery-phrase "<the words above>"
-${config.remoteStorage ? `  3. Point it at your storage:
-       sealkeep storage configure --provider ${config.remoteStorage.provider} \\
-         --bucket ${config.remoteStorage.bucket} --prefix ${config.remoteStorage.prefix}
+${ownStorage ? `  3. Point it at your storage:
+       sealkeep storage configure --provider ${ownStorage.provider} \\
+         --bucket ${ownStorage.bucket} --prefix ${ownStorage.prefix}
   4. Restore a session:  sealkeep recover <archive-id> ./restored.jsonl`
-        : options.managed ? `  3. Sign in:  sealkeep cloud login --email ${options.managed.email}
+        : managedStorage ? `  3. Sign in to Sealkeep Cloud${options.managed?.email ? `:  sealkeep cloud login --email ${options.managed.email}` : " from your account page"}
   4. See what is stored:  sealkeep cloud archives
   5. Read one back:  sealkeep open <ref> ./restored.jsonl --recovery-phrase "<the words above>"
 

package/dist/src/rehydrate.d.ts

@@ -1,43 +1,46 @@
 /**
- * Rehydration: the transparent answer to "resume is bound to a file we moved".
+ * Explicit rehydration prepares a reclaimed native transcript for a later use.
  *
- * The failure class this exists for is structural. Agents keep a catalog that
- * binds a session id to a transcript path; Sealkeep's whole point is that the
- * file can leave the disk once a sealed copy is safe. Those two facts collide
- * the moment someone resumes an old session — unless the file comes BACK
- * before the agent reads it. So: the agent's own SessionStart hook calls this,
- * and when the path is missing but the vault holds it, the newest archive of
- * that session is restored natively — exact path, exact bytes, delta chains
- * resolved, chunks fetched from the bucket if the local blob was offloaded.
- * The resume proceeds as if the file had never been away — paging, not loss.
+ * Generated agent configs do not call this automatically: Codex may already
+ * hold the pointer inode open, and downloading a multi-GB transcript on resume
+ * would defeat reclaim. The pointer instead names MCP search and the explicit
+ * safe restore command. This compatibility action remains fail-closed for
+ * callers that deliberately invoke it.
  *
- * Contract with the agent: NEVER break the session. Every outcome — including
- * "this vault has no phrase available" and "that session was never archived" —
- * is a calm JSON line and exit 0. A hook that can fail a session start would
- * be worse than the problem it solves.
+ * Contract with the agent: NEVER break session start. Every outcome — including
+ * "this vault has no phrase available" and a concurrent append — becomes a calm
+ * JSON receipt internally and exit 0 at the hook boundary.
  */
 export type RehydrateOutcome = {
     rehydrated: true;
     archiveId: string;
     output: string;
     bytes: number;
+    pointerBackup?: string;
 } | {
     rehydrated: false;
     reason: "already-present" | "no-target" | "not-archived" | "no-phrase" | "restore-failed";
     note?: string;
 };
+export type RehydrateOperations = {
+    /** Deterministic race seam: production callers never provide it. */
+    beforeCommit?: (input: {
+        archiveId: string;
+        output: string;
+        managed: boolean;
+    }) => Promise<void>;
+};
+type RehydrateOptions = {
+    home?: string;
+    operations?: RehydrateOperations;
+};
 export declare function rehydrateSession(dataDir: string, target: {
     path?: string;
     sessionId?: string;
-}, phrase: string | undefined, options?: {
-    home?: string;
-}): Promise<RehydrateOutcome>;
-/**
- * Lenient hook-payload reading, distinct from `hookEventFromStdin` on purpose:
- * that parser refuses when the transcript is unreadable, and an ABSENT
- * transcript is this feature's entire subject.
- */
+}, phrase: string | undefined, options?: RehydrateOptions): Promise<RehydrateOutcome>;
+/** Lenient because an absent transcript is this feature's subject. */
 export declare function rehydrateTargetFromPayload(stdin: string): {
     path?: string;
     sessionId?: string;
 };
+export {};