Add the LogicSRC OpenCreds specification (#140)

* Add the LogicSRC OpenCreds specification

Leaving a password manager means writing every secret you own to disk in
the clear, and losing whatever the spreadsheet had no column for. A CSV
is plaintext by construction, lossy by omission, and carries no
integrity: nothing in it says which rows were meant to be there, so a
truncated import looks exactly like a complete one.

The same gap showed up inside LogicSRC. `logicsrc credentials` moves
.env secrets and SSH keys through end-to-end-encrypted team vaults, but
it can only model a key/value pair. A card, a passport, a login with a
TOTP seed, or an OAuth account with a refresh token are all things
people already keep in a vault, and none of them are a key/value pair.

OpenCreds defines three things: the item, the vault, and the database.

- Six item types (login, card, identity, note, key, account) as one
  record with a type and a named field group, so everything the user
  typed lives in a single encrypted blob. Codes 1-4 match MarkSyncr's
  deployed vault and are not renumbered; compatibility is cheaper than
  elegance.
- AES-256-GCM over that record with the item id bound as AAD. Without
  it, anyone with storage write access could move a low-value login's
  ciphertext into a high-value row and watch what the user does next.
- A key hierarchy where the user key is random, not derived, so a
  password change re-wraps 32 bytes rather than re-encrypting a vault.
  The auth hash comes out of a different HKDF label than the wrap key,
  which is what lets it reach a server at all.
- A portable .opencreds file, encrypted by default, whose header is the
  AAD over the payload -- so the manifest is authenticated by the same
  tag as the data and a truncated import fails rather than reporting
  success. The plaintext form exists because people move to products
  that read nothing else; it is opt-in, confirmed, 0600, and labelled
  "protected": false in its own header.

Namespaces are carried as data, not fixed by the spec: labels are
compiled into every ciphertext a vault has written, so editing one does
not migrate a vault, it makes it undecryptable. MarkSyncr's deployed
vault is conformant by declaring `marksyncr`.

Ships: prd/0004, nine spec pages under docs/opencreds/, six JSON
Schemas, the @logicsrc/opencreds reference implementation with CSV
importers for five products, `logicsrc vault` and the standalone
`opencreds` binary, and the spec page at logicsrc.com/opencreds.

`vault` rather than `creds` because `creds` is already an alias of
`logicsrc credentials`, and the two are different: one moves a pair
between providers, the other stores a record.

@logicsrc/validators now registers every schema by $id before
compiling, so the database schema can $ref the item and manifest
schemas rather than restating them.

120 tests, including CLI end-to-end coverage of the masking rules,
exit codes, and the manifest-mismatch path.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QRQrfuwuYKKV5UB9kLHuX5

* Make the OpenCreds conformance claim executable

The conformance page described a fixture suite and an `opencreds
conformance` command that did not exist. A specification that documents
a conformance surface it cannot run is a specification nobody can hold
to, including us.

`opencreds conformance` now runs the requirement list as code -- one
check per C-number, carrying its own id and level -- and emits the
report shape the spec publishes. It exits 2 when a MUST does not pass,
so it can gate CI directly. The reference implementation reports 29
passed, 0 failed, 1 skipped; the skip is C19, because key management for
the team profile lives in @logicsrc/plugin-credential-sharing rather
than in this package, and a skipped MAY does not affect conformance.

Fixtures are generated (`--emit-fixtures <dir>`) rather than
hand-written. A vector produced by an implementation and then verified
by it is worth more than a JSON file someone typed: the typed file
drifts silently when the format moves, and the generated one cannot.
Fourteen files, including an invalid/ set every conforming reader must
reject -- a wrong field group, a weak KDF, an unregistered namespace, a
short payload and a tampered manifest.

The CLI requirements stay with the end-to-end tests that drive the real
binary through a child process; a command cannot meaningfully check its
own exit codes, and a masked value that is only masked in the library is
not masked.

conformance.md and cli.md now describe what ships.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QRQrfuwuYKKV5UB9kLHuX5

* Add @logicsrc/opencreds to the lockfile

`npm ci` refuses a lockfile that does not match package.json, and the
new workspace package plus the CLI's dependency on it were never
recorded: the worktree was bootstrapped by hardlinking node_modules
rather than installing, so npm was never asked to update the lock.

Adds the workspace link and the package entry. No dependency versions
move.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QRQrfuwuYKKV5UB9kLHuX5

* Register PRD 0004, and stop the fixtures looking like real secrets

Two CI failures, both mine.

`prd/README.md` is generated by `logicsrc prd index --write` and the
scaffold test asserts it is current, so adding a PRD without
regenerating it leaves the repo's own conformance check failing.
Regenerated. The MCP test asserts the next free PRD id against the live
prd/ directory — its comment says it advances with every PRD added — so
it moves to 0005.

ThreatCrush flagged three of the example strings: a PEM header in the
item-model docs and in the conformance fixture, and an `sk_live_`
prefixed token. All placeholders, none real, but the finding is the
scanner working. A fixture only has to exercise the field, and a
real-looking private key header or live-key prefix sitting in the tree
trains both the scanner and the people reading its output to shrug at
exactly the shape that matters. Replaced with obvious placeholders
rather than suppressing the rule.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QRQrfuwuYKKV5UB9kLHuX5

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

prd/0004-add-logicsrc-opencreds-spec.md

@@ -0,0 +1,185 @@
+---
+openprd: "0.2"
+id: "0004"
+title: "Add the LogicSRC OpenCreds specification"
+status: Draft
+authors:
+  - anthony@profullstack.com
+created: 2026-08-29
+updated: 2026-08-29
+repo: profullstack/logicsrc
+discussion:
+implementation:
+tags:
+  - opencreds
+  - credentials
+  - vault
+  - encryption
+  - portability
+  - schemas
+supersedes:
+superseded-by:
+---
+
+## Problem
+
+A password manager is the one application a person is least able to leave. The
+vault holds logins, cards, identity documents, private keys and the tokens that
+authorize machines to act — and every product stores them in a shape only that
+product can read. Leaving means an export, and the export is a CSV.
+
+The CSV is the whole problem in one file. It is plaintext by construction, so
+the act of moving a vault is the act of writing every secret it contains to disk
+unencrypted. It is lossy: password history, TOTP seeds, folder structure, custom
+fields and attachments have nowhere to go. It disagrees with itself between
+products, and between versions of the same product, so each importer is a pile
+of column guesses that silently drops whatever it does not recognise. And it
+carries no integrity: nothing in a CSV says which rows were meant to be there,
+so a truncated import looks exactly like a complete one.
+
+Underneath that, the same gap shows up inside LogicSRC. `logicsrc credentials`
+already moves `.env` secrets and SSH keys through end-to-end-encrypted team
+vaults, but it can only model a **key/value pair**. A credit card, a passport, a
+login with a TOTP seed and three matching URIs, or an OAuth account with a
+refresh token and a scope list are all things people already keep in a vault,
+and none of them are a key/value pair. Two Profullstack products — LogicSRC and
+MarkSyncr — grew vaults independently and ended up with two item models, two
+crypto envelopes, and no way to move a vault between them.
+
+What is missing is an open, versioned description of **what a credential record
+is, how a vault is encrypted, and what a portable vault file looks like** — so
+that moving a vault is a supported operation rather than a plaintext export.
+
+## Goals
+
+- A person can move an entire vault between two conforming implementations
+  without a single secret ever being written to disk in plaintext.
+- One item model covers what people actually store: logins, cards, identities,
+  notes, keys and accounts — not key/value pairs plus a comment field.
+- An export is lossless and self-describing: password history, TOTP seeds,
+  folders, custom fields, URI match rules and provenance survive the round trip,
+  and whatever an importer could not understand is reported rather than dropped.
+- An import can be verified before it is trusted: item counts and a digest are
+  covered by the same authentication tag as the data.
+- LogicSRC and MarkSyncr vaults become functionally identical — the same item
+  types, the same envelope, the same file — with each product's own storage and
+  UI on top.
+- A third-party implementation can conform from the published schemas and
+  fixtures without reading LogicSRC source.
+- Existing vaults stay readable. A deployed vault's domain-separation labels are
+  baked into its ciphertext and cannot be edited, so the spec carries them as a
+  declared property rather than pretending every vault in the world started
+  today.
+
+## Non-Goals
+
+- Not a hosted service. A conforming vault is a file plus a key; nothing in the
+  spec requires an account, a server, or a network call.
+- Not a sync protocol. How two devices reconcile is left to the implementation;
+  OpenCreds defines the record and the file, not the transport.
+- Not a new cipher. The spec composes PBKDF2, HKDF and AES-GCM — all available
+  in WebCrypto — rather than inventing anything.
+- Not a browser autofill standard. URI match rules are carried so they survive a
+  move; how a client fills a form is out of scope.
+- Not an attempt to hide vault size. Item type and count are deliberately
+  observable by a storage server; see the security notes.
+
+## Users
+
+- **A person leaving a password manager.** Wants their vault out, intact, and
+  not in a spreadsheet.
+- **A team sharing infrastructure credentials.** Already uses `logicsrc
+  credentials`; needs to keep a card, a signing key and a service account in the
+  same vault as the `.env` secrets.
+- **An implementer** building a vault who wants interoperability without
+  reverse-engineering someone's export.
+- **An agent** acting on behalf of a person, which must be able to read one
+  scoped item without being handed the vault.
+
+## Requirements
+
+- R1 [P0] Define six item types — `login`, `card`, `identity`, `note`, `key`,
+  `account` — each as a named field group inside one record shape, with a
+  versioned schema stamped into every record.
+- R2 [P0] Define the item envelope: AES-256-GCM over the JSON record, with the
+  item id bound as additional authenticated data so a ciphertext cannot be moved
+  between rows.
+- R3 [P0] Define the key hierarchy: a master password stretched by PBKDF2-SHA256
+  (600,000 iterations, floor 100,000), split by HKDF into a wrapping key and an
+  auth hash, wrapping a random 256-bit user key. Argon2id is reserved and carried
+  in the parameters so it can be adopted without invalidating a vault.
+- R4 [P0] Define the portable database: a single JSON file, `.opencreds`, in
+  either an encrypted form (default) or a plaintext form that must be explicitly
+  requested and is labelled as unprotected in the file itself.
+- R5 [P0] The encrypted database authenticates its own manifest — item count,
+  type histogram, and a digest over the item ids — so a truncated or tampered
+  import fails rather than silently importing less than the file claimed.
+- R6 [P0] Publish JSON Schemas for the item, the vault meta, the database, the
+  manifest and the audit event under `@logicsrc/schemas`.
+- R7 [P0] Ship a reference implementation, `@logicsrc/opencreds`, with a
+  conformance suite that runs against published fixtures.
+- R8 [P1] Define importers for the CSV exports people actually have — Bitwarden,
+  1Password, Chrome, LastPass, KeePass — mapping into the OpenCreds item model,
+  with unmapped rows reported.
+- R9 [P1] Define the CLI surface (`logicsrc vault …` and standalone `opencreds`)
+  as a conformance surface: flags, output shapes and exit codes.
+- R10 [P1] Carry a per-vault `namespace` for domain-separation labels so an
+  existing vault (`marksyncr`) is conformant without re-encrypting, while a new
+  vault uses `opencreds`.
+- R11 [P1] Define two key-management profiles over one envelope: `user` (a
+  password-derived key) and `team` (a vault key sealed to each member's public
+  key, as `logicsrc credentials` already does), so a team vault and a personal
+  vault hold the same items.
+- R12 [P2] Define attachment references so a file attached to an item has a
+  defined shape, even where an implementation does not yet store blobs.
+- R13 [P2] Publish the spec at `logicsrc.com/opencreds` with the schemas linked
+  from the page.
+
+## UX Notes
+
+Export is a deliberate, two-step act. `opencreds export` writes an encrypted
+file and says nothing about the passphrase being optional; producing the
+plaintext form requires `--plaintext`, which prints what it is about to do and
+refuses without `--yes`. The written file carries `"protected": false` in its
+header, so a plaintext database is identifiable without parsing the rest of it.
+
+Import is a preview first. `opencreds import <file> --dry-run` reports the counts
+by type, the folders it will create, the duplicates it detected and the rows it
+could not map — and only then does an unqualified `import` write. Nothing is
+written on a manifest mismatch.
+
+Failure is per-item, not per-file. One unreadable record must not hide the rest
+of a vault, so decryption collects failures and returns them alongside whatever
+it recovered.
+
+## Success Metrics
+
+- A vault exported from MarkSyncr imports into LogicSRC with byte-identical item
+  records, and back again, with no plaintext written at any point.
+- The conformance suite passes against both implementations from the same
+  fixtures.
+- Every CSV importer round-trips its product's own published sample export with
+  zero unreported drops.
+- A vault created before this spec is readable by a conforming implementation
+  without re-encryption.
+
+## Risks & Open Questions
+
+- **Plaintext export exists at all.** It has to — some people are moving *to* a
+  product that only reads CSV — and it is the single most dangerous operation in
+  the spec. Mitigated by making it explicit, labelled and non-default, not by
+  pretending nobody needs it.
+- **PBKDF2 is a compromise.** Argon2id is the better answer and needs WASM in a
+  browser, which means `wasm-unsafe-eval` in an extension CSP. Carrying the KDF
+  parameters per vault is what makes the eventual switch a migration rather than
+  a break.
+- **Metadata leaks by design.** A storage server learns how many items of each
+  type a vault holds. Hiding it costs padding and blind indexes; the spec states
+  the leak rather than obscuring it.
+- **Two profiles, one envelope.** The `team` profile's threat model differs from
+  `user` — anyone holding the vault key reads everything in it. Open question:
+  whether per-item re-wrapping is worth specifying for partial sharing, or
+  whether that belongs to a separate vault.
+- **Attachments are specified before they are stored.** Defining the reference
+  shape now avoids an incompatible retrofit; the risk is specifying a shape the
+  first real blob store does not fit.