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>

docs/opencreds/database.md

@@ -0,0 +1,127 @@
+# The OpenCreds portable database
+
+Normative rules: [spec.md §5](./spec.md#5-the-portable-database).
+
+A database is a vault as one file. It is what you hand to another product, what
+you keep as a backup, and what an implementation reads to import.
+
+## Encrypted by default
+
+```json
+{
+  "opencreds": "0.1",
+  "type": "opencreds.database",
+  "protected": true,
+  "namespace": "opencreds",
+  "exportedAt": "2026-08-29T18:00:00.000Z",
+  "generator": { "name": "@logicsrc/opencreds", "version": "0.1.0" },
+  "kdf": { "kdf": "pbkdf2-sha256", "iterations": 600000, "salt": "…" },
+  "manifest": {
+    "itemCount": 42,
+    "types": { "login": 38, "card": 2, "key": 1, "account": 1 },
+    "folderCount": 3,
+    "digest": "…"
+  },
+  "iv": "…",
+  "ciphertext": "…"
+}
+```
+
+Everything above `iv` is readable without the passphrase, and all of it is
+authenticated by the tag on `ciphertext` — the header is the AAD. So the counts
+can be shown in a preview before anyone types a passphrase, and they cannot be
+lied about.
+
+## The export key is not the vault key
+
+An export is encrypted under a key derived from an **export passphrase**, not
+under the vault's user key. A file encrypted under the user key would only open
+inside the vault it came from, which is the opposite of portable.
+
+```
+export passphrase ─PBKDF2(fresh salt, iterations)─► HKDF("<ns>:database:v1") ─► export key
+```
+
+An implementation MAY accept a raw 32-byte key instead, for machine-to-machine
+transfer; then `kdf` is absent from the file.
+
+## The manifest is the integrity check
+
+```
+digest = base64( SHA-256( item ids, sorted lexicographically, joined by "\n" ) )
+```
+
+After decrypting, recompute `itemCount`, `types`, `folderCount` and `digest`.
+Any disagreement fails the import.
+
+This is the difference between an import you can trust and a CSV. A CSV that was
+truncated at 3,000 rows imports 3,000 rows and reports success. A database that
+was truncated does not decrypt at all; one that was edited after decryption
+fails its digest. There is no state in which an implementation reports a
+complete import of an incomplete file.
+
+## The plaintext form
+
+```json
+{
+  "opencreds": "0.1",
+  "type": "opencreds.database",
+  "protected": false,
+  "namespace": "opencreds",
+  "exportedAt": "…",
+  "generator": { … },
+  "manifest": { … },
+  "folders": [ { "id": "…", "name": "Work" } ],
+  "items": [ … ]
+}
+```
+
+Every secret you own, in a file, in the clear.
+
+It exists because the products people move *to* frequently read nothing else,
+and an export format that cannot express "give me the CSV" is an export format
+people work around with a script that is worse. So it is specified, and it is
+made loud:
+
+- `protected: false` sits in the header, so tooling can identify the file
+  without parsing it.
+- The CLI requires `--plaintext` and a confirmation.
+- The file is written `0600` where the platform has modes.
+- The manifest is still present and still verified. Unauthenticated, but it
+  still catches a truncated copy or a half-finished edit.
+
+## Merging on import
+
+The spec does not mandate a merge strategy, but it names the three that exist
+and what each does to an id:
+
+| Strategy | Behaviour |
+| --- | --- |
+| `skip` | An incoming item whose id already exists is skipped. The safe default. |
+| `replace` | The existing item is overwritten. |
+| `duplicate` | The incoming item is given a fresh id and both are kept. |
+
+`duplicate` is the only one that never loses data and the only one that can
+double a vault. An implementation SHOULD default to `skip` and SHOULD report the
+count of each outcome rather than a single "imported N".
+
+Folder ids collide the same way. An incoming folder whose id exists and whose
+name differs is a conflict; the reference implementation keeps the existing
+folder and remaps incoming `folderId`s onto it.
+
+## Round-tripping
+
+A conforming export → import → export cycle MUST produce byte-identical item
+records. Specifically:
+
+- Unknown top-level item fields survive. An item written by a future version
+  passes through an older implementation without losing what it did not
+  understand.
+- Empty-string fields are not dropped and not invented. `""` and absent are
+  distinguishable and both are preserved as they arrived.
+- Timestamps are not restamped. `createdAt` and `updatedAt` belong to the item,
+  not to the transfer; an importer that touches them destroys the only evidence
+  of when a password was last rotated.
+
+The `exportedAt` and `generator` of the *file* do change, of course. They
+describe the transfer, which is the one thing that is genuinely new each time.