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/crypto.md

@@ -0,0 +1,147 @@
+# OpenCreds cryptography
+
+The normative rules are [spec.md §4](./spec.md#4-the-vault). This page explains
+why the construction is shaped the way it is, and what an implementer will get
+wrong if they skip a step.
+
+## The shape
+
+```
+master password
+      │  PBKDF2-HMAC-SHA256(salt, iterations)      ← the only expensive step
+      ▼
+ master key (32 bytes)         never encrypts anything itself
+      │
+      ├─ HKDF("<ns>:vault:wrap:v1")     → wrap key      → AES-GCM → protected user key
+      ├─ HKDF("<ns>:vault:auth:v1")     → auth hash     → server (hashed again there)
+      └─ HKDF("<ns>:vault:recovery:v1") → recovery wrap → recovery blob
+
+ user key (32 random bytes)    ← what every item is actually encrypted under
+      │
+      └─ AES-256-GCM(iv, item JSON, AAD = "<ns>:vault:item:<v>:<id>")
+```
+
+## Why the user key is random, not derived
+
+Because a master password change must not be a re-encryption of the vault. The
+user key is generated once and wrapped; changing the password re-wraps 32 bytes.
+Derive item keys from the password instead and every password change rewrites
+every item — which, on a vault of any size, is a long window in which a partial
+failure leaves half the vault openable by the old password and half by the new.
+
+It also means the recovery path costs nothing extra: a second wrapping of the
+same 32 bytes under a random recovery key, and a forgotten password is
+survivable without the server learning anything it did not already hold.
+
+## Why the auth hash cannot decrypt
+
+The wrap key and the auth hash come out of the same master key through HKDF with
+*different labels*. HKDF's guarantee is exactly this: outputs under distinct
+info strings are computationally independent. A server holding every auth hash
+it has ever seen holds nothing that helps it derive a wrap key.
+
+That is what allows the auth hash to be sent at all. A scheme that sent the
+wrapping key, or anything from which it could be recovered, would be a scheme
+where "the server cannot read the vault" is a promise rather than a property.
+
+## Why the item id is in the AAD
+
+Without it, a ciphertext is portable between rows. Anyone with write access to
+the storage — a compromised server, an operator, a leaked backup restored
+somewhere writable — could copy the ciphertext of a low-value login into the row
+of a high-value one and watch what the user does next. The user unlocks, sees
+the credential they expected to see under a name they trust, and uses it.
+
+With the id bound in, that swap fails to decrypt. The tag covers the id, and the
+id is not in the ciphertext's control.
+
+The version is in the AAD for the same reason at a different scale: it stops a
+v2 record from being replayed as a v1 record once v2 exists.
+
+## Why the KDF floor is a client-side check
+
+KDF parameters are stored with the vault and, in a hosted deployment, are served
+to the client at unlock time. That makes them attacker-controlled the moment the
+server is compromised. A client that trusts `{"iterations": 1}` performs one
+round of PBKDF2, derives an auth hash almost free, and hands an attacker who has
+been capturing auth hashes an offline guessing exercise with no work factor at
+all.
+
+So the floor is enforced where it matters — in the client, before deriving —
+and, in a database-backed deployment, again as a constraint on the column.
+Defence in depth on the one value the user cannot see.
+
+## Namespaces
+
+Every label above is prefixed by the vault's declared `namespace`. This is not
+decoration. A label is compiled into the additional authenticated data of every
+ciphertext a vault has ever written, and into the HKDF derivation of its keys.
+Change a label string and every vault in the world that used it becomes
+undecryptable — not corrupted, not recoverable, undecryptable.
+
+So labels are append-only in the strongest sense available: superseded by a new
+`:v2` label, never edited. And because MarkSyncr's vault shipped with
+`marksyncr:vault:*` labels before this specification existed, the prefix is
+carried as a per-vault property rather than fixed by the spec. A deployed vault
+declares `"namespace": "marksyncr"` and is conformant; a new one uses
+`opencreds`.
+
+Registered: `opencreds`, `marksyncr`. Pattern: `^[a-z][a-z0-9-]{1,31}$`.
+
+An implementation MUST reject an unregistered namespace on import unless the
+operator opts in, because accepting an arbitrary prefix is accepting an
+arbitrary derivation.
+
+## Profiles
+
+### `user`
+
+Everything above. One person, one master password.
+
+### `team`
+
+The vault key is random and is wrapped to each member with `crypto_box_seal`
+(X25519 anonymous sealed box) against that member's public key. The server holds
+one wrapped key per member and never the key. Granting access is an existing
+member unwrapping with their secret key and re-sealing to the new member's public
+key — the plaintext key exists only in memory, on a machine that was already
+authorized.
+
+`logicsrc credentials` implements this today for `.env` secrets and SSH keys; see
+[credential-sharing.md](../credential-sharing.md). OpenCreds adds nothing to it
+except the observation that the thing being wrapped can be a vault of items
+rather than a bag of strings.
+
+The item envelope is identical under both profiles. That is the whole point: an
+item exported from a personal vault imports into a team vault without
+re-encoding, because only the key management differed.
+
+**Threat model difference, stated plainly.** In the `team` profile, every member
+who holds the vault key can read every item in it. Revoking a member means
+rotating the key and re-encrypting, because the key they held is a key they may
+have kept. Partial sharing is not a feature of a shared key; it is a second
+vault.
+
+## Randomness
+
+Every IV, salt, user key and recovery key MUST come from a cryptographic RNG
+(`crypto.getRandomValues`, `crypto.randomBytes`). An IV MUST NOT be reused under
+one key — with GCM, a repeated IV under the same key is not a weakness, it is a
+break, and it leaks the XOR of two plaintexts along with the authentication
+subkey.
+
+Because the user key is per vault and IVs are per write, the safe construction
+is simply: generate a fresh 12-byte IV on every single encryption, never derive
+it, never count with it.
+
+## What is not covered
+
+- **Key stretching for the export passphrase** uses the same PBKDF2 parameters
+  as a vault. An export passphrase is typed once and often weaker than a master
+  password; an implementation SHOULD say so rather than silently accepting four
+  characters.
+- **Memory hygiene.** Zeroing key material after use is out of scope for the
+  format and worth doing anyway where the runtime allows it. In a browser it
+  mostly does not.
+- **Side channels.** Comparisons of secret-derived values (auth hashes, tags)
+  MUST be constant-time. Everything else in the format compares public data.