From e91d5d0be2355c4be78b8c455ddf87b66d795036 Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Thu, 13 Aug 2026 21:31:32 -0400
Subject: [PATCH] TS port slice 5: agent-blind provisioning, entry-secret
 parity, nostr app fix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- core entryOps: add* functions for all creatable kinds rebuild the Python
  EntryManager fixture index byte-for-byte under a pinned clock — field
  shapes, id allocation, independent TOTP derivation-index allocation, and
  Python's ISO timestamp format all verified.
- CLI 'entry add password/totp/key-value/document/seed/managed-account/
  nostr': provision-blind — returns the reference and metadata, never the
  secret the entry represents; tests assert the derived password / imported
  secret / child mnemonic appear nowhere in provisioning output.
- Parity bug found and fixed by the new entry_secrets fixtures: nostr ENTRY
  keys derive via the default BIP-85 app 39 path (EntryManager), not app
  1237 (sync client identity); the CLI had used 1237. Reveal values for
  password/TOTP/nostr/seed/managed-account now match Python retrieval.
- 129 core parity tests (Node + jsdom) + 16 CLI tests green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/typescript_port_compatibility_matrix.md  |   8 +-
 js/packages/cli/src/program.ts                | 161 +++++++-
 js/packages/cli/src/secrets.ts                |  13 +-
 js/packages/cli/test/cli.test.ts              |  81 ++++
 js/packages/core/src/index.ts                 |  17 +
 js/packages/core/src/vault/entryOps.ts        | 353 ++++++++++++++++++
 js/packages/core/test/entryOps.test.ts        |  85 +++++
 .../test-vectors/fixtures/entry_secrets.json  |  15 +
 .../test-vectors/fixtures/manifest.json       |   3 +-
 js/packages/test-vectors/src/index.ts         |  10 +
 scripts/generate_ts_port_fixtures.py          |  48 +++
 11 files changed, 785 insertions(+), 9 deletions(-)
 create mode 100644 js/packages/core/src/vault/entryOps.ts
 create mode 100644 js/packages/core/test/entryOps.test.ts
 create mode 100644 js/packages/test-vectors/fixtures/entry_secrets.json

diff --git a/docs/typescript_port_compatibility_matrix.md b/docs/typescript_port_compatibility_matrix.md
index 015f4b20..b1cd1d9f 100644
--- a/docs/typescript_port_compatibility_matrix.md
+++ b/docs/typescript_port_compatibility_matrix.md
@@ -36,14 +36,16 @@ until a later milestone.
 | Tombstones / delta replay | P0 | green | `delta_replay.json` | Encrypted V3 deltas decrypted and merged in order with `source_tag = sha256(payload)[:16]`, final state matches Python. |
 | index0 content merge (`_system.index0`) | P2 | partial | — | Empty-skeleton normalization matches Python; merging populated index0 event logs throws loudly instead of silently dropping data. Full port belongs to the atlas milestone. |
 | Portable backup import/export | P0 | green | `portable_backup.json` | format_version 1, seed-only and plaintext modes; TS imports the Python export, re-exports byte-identically under pinned nonce/timestamp, verifies canonical checksum, rejects tampering/unknown versions. |
-| CLI (Milestone 5, agent-blind MVP) | P1 | partial | — | `packages/cli` seedpass-js: capabilities, entry list/get/search (reference-first, `sp://entry/<id>`, secrets replaced by `has_*` flags), `entry reveal` as the only plaintext egress, `use --clipboard/--exec/--stdin-to` sinks (env-var injection, never argv/stdout), vault export/import. Tests assert secrets never appear in default output. Not yet: add/modify entries, profiles, relay sync, leases/tokens. |
+| Entry creation (provision) | P0 | green | `entries_index.json` | TS `add*Entry` ops rebuild the Python `EntryManager` fixture index byte-for-byte (pinned clock): field shapes, id allocation, independent TOTP derivation-index allocation, ISO timestamp format. Not ported: index0 event emission, modify/archive ops. |
+| Entry secret retrieval | P0 | green | `entry_secrets.json` | Reveal values match Python retrieval for password (v2), TOTP-at-time, nostr entry nsec (BIP-85 app 39 — NOT the sync client's 1237), seed and managed-account mnemonics. |
+| CLI (Milestone 5, agent-blind MVP) | P1 | partial | — | `packages/cli` seedpass-js: capabilities, entry list/get/search (reference-first, `sp://entry/<id>`, secrets replaced by `has_*` flags), `entry add password/totp/key-value/document/seed/managed-account/nostr` (provision-blind: returns refs, never the created secret), `entry reveal` as the only plaintext egress, `use --clipboard/--exec/--stdin-to` sinks (env-var injection, never argv/stdout), vault export/import. Tests assert secrets never appear in default or provisioning output. Not yet: modify/archive, profiles, relay sync, leases/tokens. |
 
 ## Environment coverage
 
 | Environment | Status |
 |---|---|
-| Node 22 (vitest) | green — 125/125 core + 11 CLI |
-| jsdom browser-like env | green — 125/125 core |
+| Node 22 (vitest) | green — 129/129 core + 16 CLI |
+| jsdom browser-like env | green — 129/129 core |
 | Real Chromium/Firefox (vitest browser mode) | todo — lands with Milestone 6 web app CI |
 
 ## Dependency notes (to expand into docs/typescript_dependency_review.md)
diff --git a/js/packages/cli/src/program.ts b/js/packages/cli/src/program.ts
index ff17dfd6..fe49ea08 100644
--- a/js/packages/cli/src/program.ts
+++ b/js/packages/cli/src/program.ts
@@ -13,8 +13,20 @@ import { entryMetadata, resolveEntry } from "./refs.js";
 import { materializeSecret } from "./secrets.js";
 import { clipboardSink, execSink, stdinSink } from "./sinks.js";
 import { capabilities } from "./capabilities.js";
-import { openVault, type OpenedVault } from "./vaultFile.js";
-import { importBackup, exportBackup, generateFingerprint } from "@seedpass/core";
+import { openVault, saveVault, type OpenedVault } from "./vaultFile.js";
+import {
+  importBackup,
+  exportBackup,
+  generateFingerprint,
+  addPasswordEntry,
+  addTotpDeterministic,
+  addTotpImported,
+  addKeyValueEntry,
+  addDocumentEntry,
+  addSeedEntry,
+  addManagedAccountEntry,
+  addNostrKeyEntry,
+} from "@seedpass/core";
 import { readFile, writeFile } from "node:fs/promises";
 
 export interface ProgramIo {
@@ -99,6 +111,151 @@ export function buildProgram(io: ProgramIo = defaultIo): Command {
       io.out(JSON.stringify(rows, null, 2));
     });
 
+  // Provisioning (plan section 9.3): create entries, get back a reference
+  // and metadata — never the secret the entry represents. Deterministic
+  // artifacts are recoverable from the seed; nothing extra to back up.
+  const add = entry.command("add").description("create entries (returns references, not secrets)");
+
+  const commonAddOptions = <T extends Command>(cmd: T): T => {
+    cmd
+      .option("--notes <text>", "notes", "")
+      .option("--tags <tag...>", "tags")
+      .option("--archived", "create archived");
+    return cmd;
+  };
+
+  async function finishAdd(vault: OpenedVault, id: string): Promise<void> {
+    await saveVault(vault);
+    const e = vault.index.entries[id]!;
+    io.out(JSON.stringify(entryMetadata(id, e), null, 2));
+  }
+
+  const commonOpts = (o: { notes?: string; tags?: string[]; archived?: boolean }) => ({
+    notes: o.notes ?? "",
+    ...(o.tags !== undefined && { tags: o.tags }),
+    ...(o.archived !== undefined && { archived: o.archived }),
+  });
+
+  commonAddOptions(
+    add
+      .command("password <label>")
+      .description("deterministic password entry (derives on demand; value never shown here)")
+      .option("--length <n>", "password length", "16")
+      .option("--username <name>", "username")
+      .option("--url <url>", "site URL"),
+  ).action(
+    async (
+      label: string,
+      o: { length: string; username?: string; url?: string; notes?: string; tags?: string[]; archived?: boolean },
+    ) => {
+      const vault = await openFromOptions(program.opts());
+      const id = addPasswordEntry(vault.index, label, Number(o.length), {
+        ...commonOpts(o),
+        ...(o.username !== undefined && { username: o.username }),
+        ...(o.url !== undefined && { url: o.url }),
+      });
+      await finishAdd(vault, id);
+    },
+  );
+
+  commonAddOptions(
+    add
+      .command("totp <label>")
+      .description("TOTP entry: deterministic by default, or --secret to import")
+      .option("--secret <b32>", "import an existing base32 secret")
+      .option("--period <s>", "period seconds", "30")
+      .option("--digits <n>", "code digits", "6"),
+  ).action(
+    async (
+      label: string,
+      o: { secret?: string; period: string; digits: string; notes?: string; tags?: string[]; archived?: boolean },
+    ) => {
+      const vault = await openFromOptions(program.opts());
+      const opts = {
+        ...commonOpts(o),
+        period: Number(o.period),
+        digits: Number(o.digits),
+      };
+      const id = o.secret
+        ? addTotpImported(vault.index, label, o.secret, opts)
+        : addTotpDeterministic(vault.index, label, vault.mnemonic, opts);
+      await finishAdd(vault, id);
+    },
+  );
+
+  commonAddOptions(
+    add
+      .command("key-value <label> <key> <value>")
+      .description("store an arbitrary secret value"),
+  ).action(
+    async (
+      label: string,
+      key: string,
+      value: string,
+      o: { notes?: string; tags?: string[]; archived?: boolean },
+    ) => {
+      const vault = await openFromOptions(program.opts());
+      const id = addKeyValueEntry(vault.index, label, key, value, commonOpts(o));
+      await finishAdd(vault, id);
+    },
+  );
+
+  commonAddOptions(
+    add
+      .command("document <label> <content>")
+      .description("store a text document")
+      .option("--file-type <ext>", "file type", "txt"),
+  ).action(
+    async (
+      label: string,
+      content: string,
+      o: { fileType: string; notes?: string; tags?: string[]; archived?: boolean },
+    ) => {
+      const vault = await openFromOptions(program.opts());
+      const id = addDocumentEntry(vault.index, label, content, {
+        ...commonOpts(o),
+        fileType: o.fileType,
+      });
+      await finishAdd(vault, id);
+    },
+  );
+
+  commonAddOptions(
+    add
+      .command("seed <label>")
+      .description("derived seed phrase entry (12/18/24 words)")
+      .option("--words <n>", "word count", "24"),
+  ).action(
+    async (label: string, o: { words: string; notes?: string; tags?: string[]; archived?: boolean }) => {
+      const vault = await openFromOptions(program.opts());
+      const words = Number(o.words);
+      if (words !== 12 && words !== 18 && words !== 24) {
+        throw new Error("--words must be 12, 18 or 24");
+      }
+      const id = addSeedEntry(vault.index, label, {
+        ...commonOpts(o),
+        wordCount: words as 12 | 18 | 24,
+      });
+      await finishAdd(vault, id);
+    },
+  );
+
+  commonAddOptions(
+    add.command("managed-account <label>").description("BIP-85 managed account (12-word child seed)"),
+  ).action(async (label: string, o: { notes?: string; tags?: string[]; archived?: boolean }) => {
+    const vault = await openFromOptions(program.opts());
+    const id = addManagedAccountEntry(vault.index, label, vault.mnemonic, commonOpts(o));
+    await finishAdd(vault, id);
+  });
+
+  commonAddOptions(
+    add.command("nostr <label>").description("derived Nostr key entry"),
+  ).action(async (label: string, o: { notes?: string; tags?: string[]; archived?: boolean }) => {
+    const vault = await openFromOptions(program.opts());
+    const id = addNostrKeyEntry(vault.index, label, commonOpts(o));
+    await finishAdd(vault, id);
+  });
+
   entry
     .command("reveal <refOrQuery>")
     .description("PLAINTEXT EGRESS: print the secret to stdout")
diff --git a/js/packages/cli/src/secrets.ts b/js/packages/cli/src/secrets.ts
index f6d20cd9..fa2611d0 100644
--- a/js/packages/cli/src/secrets.ts
+++ b/js/packages/cli/src/secrets.ts
@@ -11,7 +11,8 @@ import {
   generatePassword,
   deriveTotpSecret,
   totpCodeAt,
-  deriveNostrKeys,
+  hexToBech32,
+  bytesToHex,
   type Entry,
   type VaultIndex,
 } from "@seedpass/core";
@@ -56,9 +57,15 @@ export function materializeSecret(
     case "document":
       return { value: entry.content, descriptor: `document ${entry.label}` };
     case "nostr": {
+      // Nostr ENTRY keys use the default BIP-85 app 39 path (see
+      // EntryManager.get_nostr_key_pair) — NOT app 1237, which is only for
+      // the sync client identity.
       const bip85 = Bip85.fromMnemonic(mnemonic);
-      const keys = deriveNostrKeys(bip85, entry.index);
-      return { value: keys.nsec, descriptor: `nsec for ${entry.label}` };
+      const entropy = bip85.deriveEntropy({ index: entry.index, entropyBytes: 32 });
+      return {
+        value: hexToBech32(bytesToHex(entropy), "nsec"),
+        descriptor: `nsec for ${entry.label}`,
+      };
     }
     case "seed":
     case "managed_account": {
diff --git a/js/packages/cli/test/cli.test.ts b/js/packages/cli/test/cli.test.ts
index 23ee536b..7e2a12f0 100644
--- a/js/packages/cli/test/cli.test.ts
+++ b/js/packages/cli/test/cli.test.ts
@@ -13,6 +13,7 @@ import { join } from "node:path";
 import process from "node:process";
 import {
   entriesIndex,
+  entrySecrets,
   passwordV2Cases,
   totpCases,
   mnemonics,
@@ -123,6 +124,86 @@ describe("plaintext egress is explicit and correct", () => {
     const r = await run("--vault", vaultPath, "entry", "reveal", "api-token");
     expect(r.stdout).toBe("abc123");
   });
+
+  it("reveal matches every Python-computed entry secret", async () => {
+    expect((await run("--vault", vaultPath, "entry", "reveal", "example.com")).stdout).toBe(
+      entrySecrets.password_entry_0,
+    );
+    expect(
+      (await run("--vault", vaultPath, "entry", "reveal", "example-totp", "--at", "1700000000"))
+        .stdout,
+    ).toBe(entrySecrets.totp_entry_1_code_at["1700000000"]);
+    // Nostr entries use BIP-85 app 39 (not the sync client's app 1237)
+    expect((await run("--vault", vaultPath, "entry", "reveal", "example-nostr")).stdout).toBe(
+      entrySecrets.nostr_entry_4.nsec,
+    );
+    expect((await run("--vault", vaultPath, "entry", "reveal", "example-seed")).stdout).toBe(
+      entrySecrets.seed_entry_7_mnemonic,
+    );
+    expect((await run("--vault", vaultPath, "entry", "reveal", "example-managed")).stdout).toBe(
+      entrySecrets.managed_entry_8_mnemonic,
+    );
+  });
+});
+
+describe("provisioning is agent-blind", () => {
+  let writablePath: string;
+
+  beforeAll(async () => {
+    const dir = await mkdtemp(join(tmpdir(), "seedpass-provision-"));
+    writablePath = join(dir, "vault.enc");
+    await writeFile(writablePath, await readFile(vaultPath));
+  });
+
+  it("entry add password returns a reference, never the derived password", async () => {
+    const r = await run(
+      "--vault", writablePath, "entry", "add", "password", "new-site.example",
+      "--length", "16", "--username", "bob",
+    );
+    const row = JSON.parse(r.stdout);
+    expect(row.ref).toBe("sp://entry/10");
+    expect(row.kind).toBe("password");
+    expect(row.gen_version).toBe(2);
+
+    // The derived password exists and reveals correctly, but appeared
+    // nowhere in the provisioning output.
+    const reveal = await run("--vault", writablePath, "entry", "reveal", "sp://entry/10");
+    expect(reveal.stdout).toHaveLength(16);
+    expect(r.stdout).not.toContain(reveal.stdout);
+  });
+
+  it("entry add totp --secret stores but never echoes the imported secret", async () => {
+    const secret = "GEZDGNBVGY3TQOJQ";
+    const r = await run(
+      "--vault", writablePath, "entry", "add", "totp", "imported-2", "--secret", secret,
+    );
+    const row = JSON.parse(r.stdout);
+    expect(row.has_secret).toBe(true);
+    expect(r.stdout).not.toContain(secret);
+  });
+
+  it("entry add key-value persists across reopen", async () => {
+    await run(
+      "--vault", writablePath, "entry", "add", "key-value", "deploy-token", "token", "s3cr3t-value",
+    );
+    const list = await run("--vault", writablePath, "entry", "list");
+    const rows = JSON.parse(list.stdout) as { label: string }[];
+    expect(rows.map((x) => x.label)).toContain("deploy-token");
+    expect(list.stdout).not.toContain("s3cr3t-value");
+    const reveal = await run("--vault", writablePath, "entry", "reveal", "deploy-token");
+    expect(reveal.stdout).toBe("s3cr3t-value");
+  });
+
+  it("entry add managed-account records the child fingerprint only", async () => {
+    const r = await run("--vault", writablePath, "entry", "add", "managed-account", "child-acct");
+    const row = JSON.parse(r.stdout);
+    expect(row.fingerprint).toMatch(/^[0-9A-F]{16}$/);
+    expect(row.word_count).toBe(12);
+    // The child mnemonic is derivable but was never printed
+    const reveal = await run("--vault", writablePath, "entry", "reveal", "child-acct");
+    expect(reveal.stdout.split(" ")).toHaveLength(12);
+    expect(r.stdout).not.toContain(reveal.stdout);
+  });
 });
 
 describe("sink delivery keeps secrets out of CLI output", () => {
diff --git a/js/packages/core/src/index.ts b/js/packages/core/src/index.ts
index e57b727d..e873fc03 100644
--- a/js/packages/core/src/index.ts
+++ b/js/packages/core/src/index.ts
@@ -63,6 +63,23 @@ export {
   PORTABLE_FORMAT_VERSION,
   type PortableBackup,
 } from "./vault/portableBackup.js";
+export {
+  addPasswordEntry,
+  addTotpDeterministic,
+  addTotpImported,
+  addSshKeyEntry,
+  addNostrKeyEntry,
+  addKeyValueEntry,
+  addDocumentEntry,
+  addSeedEntry,
+  addManagedAccountEntry,
+  addPgpKeyEntry,
+  nextIndex,
+  nextTotpIndex,
+  isoFromUnix,
+  systemClock,
+  type Clock,
+} from "./vault/entryOps.js";
 export { canonicalJson, canonicalHash } from "./sync/canonical.js";
 export {
   mergeIndexPayloads,
diff --git a/js/packages/core/src/vault/entryOps.ts b/js/packages/core/src/vault/entryOps.ts
new file mode 100644
index 00000000..f87ccd43
--- /dev/null
+++ b/js/packages/core/src/vault/entryOps.ts
@@ -0,0 +1,353 @@
+/**
+ * Entry creation — the provision half of the agent-blind lifecycle
+ * (plan section 9.3).
+ *
+ * Parity target: src/seedpass/core/entry_management.py add_* methods. Each
+ * function appends an entry to the index and returns its id; none of them
+ * return secret material. Field shapes match Python exactly (the parity test
+ * rebuilds the Python-generated fixture index from scratch).
+ *
+ * Not ported here: Python's index0 event emission (`_system` bookkeeping),
+ * checksum/backup side effects, and creation-time validation of derived
+ * SSH/PGP key pairs (that key material is not ported yet).
+ */
+
+import { deriveTotpSecret } from "../derive/totp.js";
+import { generateFingerprint } from "../derive/fingerprint.js";
+import { Bip85 } from "../derive/bip85.js";
+import { CURRENT_PASSWORD_GEN_VERSION } from "../derive/password.js";
+import type { VaultIndex } from "../schema/entries.js";
+
+type Dict = Record<string, unknown>;
+
+export interface Clock {
+  nowUnix(): number;
+}
+
+export const systemClock: Clock = {
+  nowUnix: () => Math.floor(Date.now() / 1000),
+};
+
+/** Python: datetime.fromtimestamp(ts, tz=utc).isoformat() -> "+00:00" suffix. */
+export function isoFromUnix(ts: number): string {
+  const iso = new Date(Math.trunc(ts) * 1000).toISOString();
+  return iso.replace(/\.\d{3}Z$/, "+00:00");
+}
+
+/** max(int keys) + 1, or 0 for an empty index (get_next_index). */
+export function nextIndex(index: VaultIndex): number {
+  const ids = Object.keys(index.entries).map((k) => parseInt(k, 10));
+  return ids.length > 0 ? Math.max(...ids) + 1 : 0;
+}
+
+/** Next TOTP derivation index: max over totp entries' index field + 1. */
+export function nextTotpIndex(index: VaultIndex): number {
+  const indices = Object.values(index.entries as unknown as Record<string, Dict>)
+    .filter((e) => e["type"] === "totp" || e["kind"] === "totp")
+    .map((e) => Math.trunc(Number(e["index"] ?? 0)));
+  return indices.length > 0 ? Math.max(...indices) + 1 : 0;
+}
+
+function stamp(clock: Clock): { now_unix: number; now_iso: string } {
+  const nowUnix = clock.nowUnix();
+  return { now_unix: nowUnix, now_iso: isoFromUnix(nowUnix) };
+}
+
+function insert(index: VaultIndex, id: number, entry: Dict): string {
+  (index.entries as unknown as Dict)[String(id)] = entry;
+  return String(id);
+}
+
+export interface CommonOptions {
+  archived?: boolean;
+  notes?: string;
+  tags?: string[];
+  clock?: Clock;
+}
+
+export interface AddPasswordOptions extends CommonOptions {
+  username?: string;
+  url?: string;
+  customFields?: Dict[];
+  policy?: Partial<{
+    include_special_chars: boolean;
+    allowed_special_chars: string;
+    special_mode: string;
+    exclude_ambiguous: boolean;
+    min_uppercase: number;
+    min_lowercase: number;
+    min_digits: number;
+    min_special: number;
+  }>;
+}
+
+export function addPasswordEntry(
+  index: VaultIndex,
+  label: string,
+  length: number,
+  opts: AddPasswordOptions = {},
+): string {
+  const id = nextIndex(index);
+  const { now_unix, now_iso } = stamp(opts.clock ?? systemClock);
+  const entry: Dict = {
+    label,
+    length,
+    gen_version: CURRENT_PASSWORD_GEN_VERSION,
+    username: opts.username ?? "",
+    url: opts.url ?? "",
+    archived: opts.archived ?? false,
+    type: "password",
+    kind: "password",
+    notes: opts.notes ?? "",
+    modified_ts: now_unix,
+    date_added: now_iso,
+    date_modified: now_iso,
+    custom_fields: opts.customFields ?? [],
+    tags: opts.tags ?? [],
+    links: [],
+  };
+  if (opts.policy && Object.keys(opts.policy).length > 0) {
+    entry["policy"] = { ...opts.policy };
+  }
+  return insert(index, id, entry);
+}
+
+export interface AddTotpOptions extends CommonOptions {
+  period?: number;
+  digits?: number;
+  /** Derivation index for deterministic secrets; auto-allocated if omitted. */
+  index?: number;
+}
+
+/** Deterministic TOTP: the secret derives from the parent seed on demand. */
+export function addTotpDeterministic(
+  index: VaultIndex,
+  label: string,
+  mnemonic: string,
+  opts: AddTotpOptions = {},
+): string {
+  const id = nextIndex(index);
+  const derivationIndex = opts.index ?? nextTotpIndex(index);
+  // Derive once to validate, exactly as Python does — the value is dropped.
+  deriveTotpSecret(mnemonic, derivationIndex);
+  const { now_unix, now_iso } = stamp(opts.clock ?? systemClock);
+  return insert(index, id, {
+    type: "totp",
+    kind: "totp",
+    label,
+    modified_ts: now_unix,
+    date_added: now_iso,
+    date_modified: now_iso,
+    index: derivationIndex,
+    period: opts.period ?? 30,
+    digits: opts.digits ?? 6,
+    archived: opts.archived ?? false,
+    notes: opts.notes ?? "",
+    tags: opts.tags ?? [],
+    deterministic: true,
+    links: [],
+  });
+}
+
+const B32_RE = /^[A-Z2-7]+=*$/;
+
+/** Imported TOTP: stores the provided base32 secret. */
+export function addTotpImported(
+  index: VaultIndex,
+  label: string,
+  secret: string,
+  opts: AddTotpOptions = {},
+): string {
+  const normalized = secret.trim().toUpperCase();
+  if (!B32_RE.test(normalized)) throw new Error("Invalid TOTP secret");
+  const id = nextIndex(index);
+  const { now_unix, now_iso } = stamp(opts.clock ?? systemClock);
+  return insert(index, id, {
+    type: "totp",
+    kind: "totp",
+    label,
+    secret: normalized,
+    modified_ts: now_unix,
+    date_added: now_iso,
+    date_modified: now_iso,
+    period: opts.period ?? 30,
+    digits: opts.digits ?? 6,
+    archived: opts.archived ?? false,
+    notes: opts.notes ?? "",
+    tags: opts.tags ?? [],
+    deterministic: false,
+    links: [],
+  });
+}
+
+export function addSshKeyEntry(
+  index: VaultIndex,
+  label: string,
+  opts: CommonOptions & { index?: number } = {},
+): string {
+  const id = opts.index ?? nextIndex(index);
+  const { now_unix, now_iso } = stamp(opts.clock ?? systemClock);
+  return insert(index, id, {
+    type: "ssh",
+    kind: "ssh",
+    index: id,
+    label,
+    modified_ts: now_unix,
+    date_added: now_iso,
+    date_modified: now_iso,
+    notes: opts.notes ?? "",
+    archived: opts.archived ?? false,
+    tags: opts.tags ?? [],
+    custom_fields: [],
+    links: [],
+  });
+}
+
+export function addNostrKeyEntry(
+  index: VaultIndex,
+  label: string,
+  opts: CommonOptions & { index?: number } = {},
+): string {
+  const id = opts.index ?? nextIndex(index);
+  const { now_unix, now_iso } = stamp(opts.clock ?? systemClock);
+  return insert(index, id, {
+    type: "nostr",
+    kind: "nostr",
+    index: id,
+    label,
+    modified_ts: now_unix,
+    date_added: now_iso,
+    date_modified: now_iso,
+    notes: opts.notes ?? "",
+    archived: opts.archived ?? false,
+    tags: opts.tags ?? [],
+    links: [],
+  });
+}
+
+export function addKeyValueEntry(
+  index: VaultIndex,
+  label: string,
+  key: string,
+  value: string,
+  opts: CommonOptions & { customFields?: Dict[] } = {},
+): string {
+  const id = nextIndex(index);
+  const { now_unix, now_iso } = stamp(opts.clock ?? systemClock);
+  return insert(index, id, {
+    type: "key_value",
+    kind: "key_value",
+    label,
+    key,
+    value,
+    modified_ts: now_unix,
+    date_added: now_iso,
+    date_modified: now_iso,
+    notes: opts.notes ?? "",
+    archived: opts.archived ?? false,
+    tags: opts.tags ?? [],
+    custom_fields: opts.customFields ?? [],
+    links: [],
+  });
+}
+
+export function addDocumentEntry(
+  index: VaultIndex,
+  label: string,
+  content: string,
+  opts: CommonOptions & { fileType?: string } = {},
+): string {
+  const id = nextIndex(index);
+  const { now_unix, now_iso } = stamp(opts.clock ?? systemClock);
+  return insert(index, id, {
+    type: "document",
+    kind: "document",
+    label,
+    content,
+    file_type: opts.fileType ?? "txt",
+    modified_ts: now_unix,
+    date_added: now_iso,
+    date_modified: now_iso,
+    notes: opts.notes ?? "",
+    archived: opts.archived ?? false,
+    tags: opts.tags ?? [],
+    custom_fields: [],
+    links: [],
+  });
+}
+
+export function addSeedEntry(
+  index: VaultIndex,
+  label: string,
+  opts: CommonOptions & { index?: number; wordCount?: 12 | 18 | 24 } = {},
+): string {
+  const id = opts.index ?? nextIndex(index);
+  const { now_unix, now_iso } = stamp(opts.clock ?? systemClock);
+  return insert(index, id, {
+    type: "seed",
+    kind: "seed",
+    index: id,
+    label,
+    modified_ts: now_unix,
+    date_added: now_iso,
+    date_modified: now_iso,
+    word_count: opts.wordCount ?? 24,
+    notes: opts.notes ?? "",
+    archived: opts.archived ?? false,
+    tags: opts.tags ?? [],
+    links: [],
+  });
+}
+
+/** Managed accounts always use a 12-word child seed. */
+export function addManagedAccountEntry(
+  index: VaultIndex,
+  label: string,
+  mnemonic: string,
+  opts: CommonOptions & { index?: number } = {},
+): string {
+  const id = opts.index ?? nextIndex(index);
+  const child = Bip85.fromMnemonic(mnemonic).deriveMnemonic(id, 12);
+  const fingerprint = generateFingerprint(child);
+  const { now_unix, now_iso } = stamp(opts.clock ?? systemClock);
+  return insert(index, id, {
+    type: "managed_account",
+    kind: "managed_account",
+    index: id,
+    label,
+    modified_ts: now_unix,
+    date_added: now_iso,
+    date_modified: now_iso,
+    word_count: 12,
+    notes: opts.notes ?? "",
+    fingerprint,
+    archived: opts.archived ?? false,
+    tags: opts.tags ?? [],
+    custom_fields: [],
+    links: [],
+  });
+}
+
+export function addPgpKeyEntry(
+  index: VaultIndex,
+  label: string,
+  opts: CommonOptions & { index?: number; keyType?: string; userId?: string } = {},
+): string {
+  const id = opts.index ?? nextIndex(index);
+  const { now_unix, now_iso } = stamp(opts.clock ?? systemClock);
+  return insert(index, id, {
+    type: "pgp",
+    kind: "pgp",
+    index: id,
+    label,
+    modified_ts: now_unix,
+    date_added: now_iso,
+    date_modified: now_iso,
+    key_type: opts.keyType ?? "ed25519",
+    user_id: opts.userId ?? "",
+    notes: opts.notes ?? "",
+    archived: opts.archived ?? false,
+    tags: opts.tags ?? [],
+    links: [],
+  });
+}
diff --git a/js/packages/core/test/entryOps.test.ts b/js/packages/core/test/entryOps.test.ts
new file mode 100644
index 00000000..587db075
--- /dev/null
+++ b/js/packages/core/test/entryOps.test.ts
@@ -0,0 +1,85 @@
+/**
+ * Entry-creation parity: rebuild the Python EntryManager-generated fixture
+ * index from scratch with the same calls and a pinned clock, and require
+ * deep equality. Any drift in field shapes, index allocation, or timestamp
+ * formatting fails here.
+ */
+
+import { describe, expect, it } from "vitest";
+import { entriesIndex, mnemonics } from "@seedpass/test-vectors";
+import {
+  addPasswordEntry,
+  addTotpDeterministic,
+  addTotpImported,
+  addSshKeyEntry,
+  addNostrKeyEntry,
+  addKeyValueEntry,
+  addDocumentEntry,
+  addSeedEntry,
+  addManagedAccountEntry,
+  addPgpKeyEntry,
+  parseVaultIndex,
+  type Clock,
+  type VaultIndex,
+} from "@seedpass/core";
+
+const FIXED_UNIX = 1700000000;
+const clock: Clock = { nowUnix: () => FIXED_UNIX };
+const MNEMONIC = mnemonics["abandon12"]!;
+
+describe("entry creation parity", () => {
+  it("rebuilds the fixture index byte-for-byte", () => {
+    const index = { schema_version: 4, entries: {} } as unknown as VaultIndex;
+
+    // Mirrors scripts/generate_ts_port_fixtures.py::_build_entries_index
+    addPasswordEntry(index, "example.com", 16, {
+      username: "alice",
+      url: "https://example.com",
+      notes: "password note",
+      tags: ["web"],
+      clock,
+    });
+    addTotpDeterministic(index, "example-totp", MNEMONIC, { tags: ["otp"], clock });
+    addTotpImported(index, "imported-totp", "JBSWY3DPEHPK3PXP", {
+      period: 45,
+      digits: 8,
+      clock,
+    });
+    addSshKeyEntry(index, "example-ssh", { notes: "ssh note", clock });
+    addNostrKeyEntry(index, "example-nostr", { clock });
+    addKeyValueEntry(index, "api-token", "token", "abc123", { tags: ["api"], clock });
+    addDocumentEntry(index, "example-doc", "hello fixture world", { clock });
+    addSeedEntry(index, "example-seed", { wordCount: 24, clock });
+    addManagedAccountEntry(index, "example-managed", MNEMONIC, { clock });
+    addPgpKeyEntry(index, "example-pgp", { userId: "fixture@example.com", clock });
+
+    expect(JSON.parse(JSON.stringify(index))).toEqual(entriesIndex.entries);
+  });
+
+  it("produces schema-valid entries", () => {
+    const index = { schema_version: 4, entries: {} } as unknown as VaultIndex;
+    addPasswordEntry(index, "x.com", 20, { clock });
+    addTotpDeterministic(index, "x-totp", MNEMONIC, { clock });
+    expect(() => parseVaultIndex(JSON.parse(JSON.stringify(index)))).not.toThrow();
+  });
+
+  it("allocates ids and totp derivation indices independently", () => {
+    const index = { schema_version: 4, entries: {} } as unknown as VaultIndex;
+    addPasswordEntry(index, "a", 16, { clock });
+    addPasswordEntry(index, "b", 16, { clock });
+    const totpId = addTotpDeterministic(index, "t1", MNEMONIC, { clock });
+    expect(totpId).toBe("2");
+    const entry = (index.entries as Record<string, { index?: number }>)["2"]!;
+    expect(entry.index).toBe(0); // first TOTP derivation index despite id 2
+    addTotpDeterministic(index, "t2", MNEMONIC, { clock });
+    const entry2 = (index.entries as Record<string, { index?: number }>)["3"]!;
+    expect(entry2.index).toBe(1);
+  });
+
+  it("rejects invalid imported TOTP secrets", () => {
+    const index = { schema_version: 4, entries: {} } as unknown as VaultIndex;
+    expect(() => addTotpImported(index, "bad", "not base32!", { clock })).toThrow(
+      "Invalid TOTP secret",
+    );
+  });
+});
diff --git a/js/packages/test-vectors/fixtures/entry_secrets.json b/js/packages/test-vectors/fixtures/entry_secrets.json
new file mode 100644
index 00000000..627bc435
--- /dev/null
+++ b/js/packages/test-vectors/fixtures/entry_secrets.json
@@ -0,0 +1,15 @@
+{
+  "description": "Expected plaintext values for entries in entries_index.json, computed via the same functions EntryManager retrieval uses. Nostr entry keys use the DEFAULT BIP-85 app 39 path, unlike the sync client identity (app 1237).",
+  "fixture_version": 1,
+  "managed_entry_8_mnemonic": "dinosaur vendor juice emerge faith wisdom kit gas limb tool maze wheel",
+  "mnemonic_id": "abandon12",
+  "nostr_entry_4": {
+    "npub": "npub1nrs92pqgqqpwrewjpzgn0vg73vzzr6nh9597aqs7h6d0xfw0vadqd5wxg3",
+    "nsec": "nsec1syfdyfwttm5c6p3cjwkn90lrz0kqkzh678eh0zpkxugvvvgn9rcsle093m"
+  },
+  "password_entry_0": "SVH883gxX?9m'3En",
+  "seed_entry_7_mnemonic": "music whip guide marriage educate lizard phone jeans key very chest provide lonely potato tower exercise shop sniff snow extra rose quarter they choice",
+  "totp_entry_1_code_at": {
+    "1700000000": "919492"
+  }
+}
diff --git a/js/packages/test-vectors/fixtures/manifest.json b/js/packages/test-vectors/fixtures/manifest.json
index 7d5cacdd..aec25cf5 100644
--- a/js/packages/test-vectors/fixtures/manifest.json
+++ b/js/packages/test-vectors/fixtures/manifest.json
@@ -5,6 +5,7 @@
     "bip85_entropy.json",
     "delta_replay.json",
     "entries_index.json",
+    "entry_secrets.json",
     "fingerprints.json",
     "index_keys.json",
     "kdf_metadata.json",
@@ -22,6 +23,6 @@
   ],
   "fixture_version": 1,
   "generator": "scripts/generate_ts_port_fixtures.py",
-  "python_commit": "2345f614310a701a147872e81c53ccd22f8948d3",
+  "python_commit": "ab569fe900213937a21f0616057d3d5c46015e3c",
   "redaction_policy": "All fixtures derive from public BIP-39 test mnemonics (abandon.../legal.../zoo...). Secret-shaped outputs are generated test material, never from a live profile."
 }
diff --git a/js/packages/test-vectors/src/index.ts b/js/packages/test-vectors/src/index.ts
index 7db51080..0f0dc72c 100644
--- a/js/packages/test-vectors/src/index.ts
+++ b/js/packages/test-vectors/src/index.ts
@@ -26,6 +26,7 @@ import nostrSnapshotJson from "../fixtures/nostr_snapshot.json";
 import syncMergeJson from "../fixtures/sync_merge.json";
 import deltaReplayJson from "../fixtures/delta_replay.json";
 import portableBackupJson from "../fixtures/portable_backup.json";
+import entrySecretsJson from "../fixtures/entry_secrets.json";
 
 export interface Bip39Case {
   id: string;
@@ -203,6 +204,15 @@ export const portableBackup = portableBackupJson as {
   plaintext_wrapper: PortableWrapper;
 };
 
+export const entrySecrets = entrySecretsJson as {
+  mnemonic_id: string;
+  password_entry_0: string;
+  totp_entry_1_code_at: Record<string, string>;
+  nostr_entry_4: { nsec: string; npub: string };
+  seed_entry_7_mnemonic: string;
+  managed_entry_8_mnemonic: string;
+};
+
 export const legacyPayloads = legacyPayloadsJson as {
   mnemonic_id: string;
   plaintext_utf8: string;
diff --git a/scripts/generate_ts_port_fixtures.py b/scripts/generate_ts_port_fixtures.py
index 737d5c85..50ae64e7 100644
--- a/scripts/generate_ts_port_fixtures.py
+++ b/scripts/generate_ts_port_fixtures.py
@@ -859,6 +859,53 @@ def gen_portable_backup(entries: dict) -> dict:
     }
 
 
+def gen_entry_secrets() -> dict:
+    """Expected reveal values for the fixture vault, via the same low-level
+    functions EntryManager retrieval uses."""
+    from nostr.coincurve_keys import Keys
+    from seedpass.core.password_generation import (
+        PasswordGenerator,
+        PasswordPolicy,
+        derive_seed_phrase,
+    )
+
+    mnemonic = MNEMONICS[PRIMARY]
+    bip85 = _bip85(mnemonic)
+
+    # Entry 0: password, length 16, gen_version 2, derivation index 0
+    pg = PasswordGenerator(_SeedDeriver(), mnemonic, bip85, policy=PasswordPolicy())
+    password = pg.generate_password(length=16, index=0, gen_version=2)
+
+    # Entry 1: deterministic TOTP, derivation index 0
+    totp_secret = derive_totp_secret(mnemonic, 0)
+    totp_code = TotpManager.current_code_from_secret(totp_secret, FIXED_UNIX)
+
+    # Entry 4: nostr key entry — DEFAULT BIP-85 app 39 (not 1237)
+    entropy = bip85.derive_entropy(index=4, entropy_bytes=32)
+    nostr_keys = Keys(priv_k=entropy.hex())
+    nsec = Keys.hex_to_bech32(nostr_keys.private_key_hex(), "nsec")
+    npub = Keys.hex_to_bech32(nostr_keys.public_key_hex(), "npub")
+
+    # Entry 7: seed entry, index 7, 24 words; entry 8: managed account, 12 words
+    seed_phrase = derive_seed_phrase(bip85, 7, 24)
+    managed_phrase = derive_seed_phrase(bip85, 8, 12)
+
+    return {
+        "description": (
+            "Expected plaintext values for entries in entries_index.json, "
+            "computed via the same functions EntryManager retrieval uses. "
+            "Nostr entry keys use the DEFAULT BIP-85 app 39 path, unlike the "
+            "sync client identity (app 1237)."
+        ),
+        "mnemonic_id": PRIMARY,
+        "password_entry_0": password,
+        "totp_entry_1_code_at": {str(FIXED_UNIX): totp_code},
+        "nostr_entry_4": {"nsec": nsec, "npub": npub},
+        "seed_entry_7_mnemonic": seed_phrase,
+        "managed_entry_8_mnemonic": managed_phrase,
+    }
+
+
 def gen_kdf_metadata() -> dict:
     return {
         "description": (
@@ -909,6 +956,7 @@ def main() -> None:
     files["vault_v3_payload.json"] = vault_fixture
     files["nostr_snapshot.json"] = gen_nostr_snapshot(vault_fixture["payload_b64"])
     files["portable_backup.json"] = gen_portable_backup(entries_fixture["entries"])
+    files["entry_secrets.json"] = gen_entry_secrets()
     files["sync_merge.json"] = gen_sync_merge()
     files["delta_replay.json"] = gen_delta_replay()