Initial Commit
This commit is contained in:
@@ -0,0 +1,150 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: bitpacker-crypto (extract-shared-crypto-interfaces)
|
||||
|
||||
**Package**: `@suaveplan/bitpacker-crypto`
|
||||
**Status**: PROPOSED — gated on user sign-off of the API shape
|
||||
|
||||
> Modifies the four DI-using primitives shipped by the archived
|
||||
> `bitpacker-crypto-rewrite` (2026-05-02) to accept `verifier` and
|
||||
> `aead` via dependency injection. No wire-format change.
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: SignedBitSchema integrates with Authority + DomainTag (verifier injected)
|
||||
|
||||
The `defineSignedBitSchema<T>(bodyCodec, options)` function SHALL
|
||||
accept a required `verifier: AuthorityVerifier` field on its options
|
||||
bundle. The primitive SHALL call `verifier(domain, parentPublicSlot,
|
||||
body, signature)` instead of importing `verifyAuthoritySignature`
|
||||
directly. All other behavior (verify-then-decode order, `unpackSelf`
|
||||
trust-anchor flow, cross-domain replay rejection, `CRYPTO_VERIFY_FAILED`
|
||||
on tamper) remains identical to the archived `bitpacker-crypto-rewrite`
|
||||
spec.
|
||||
|
||||
The primitive SHALL import `Authority`, `AuthorityVerifier`, `DomainTag`,
|
||||
`KeySlotPublic`, and `SlotId` types from `@suaveplan/types` instead of
|
||||
from `@suaveplan/crypto/authority` and `@suaveplan/crypto/domain-tags`.
|
||||
|
||||
#### Scenario: missing `verifier` rejects at construction time
|
||||
|
||||
- **WHEN** `defineSignedBitSchema(codec, { domain: D })` is called
|
||||
WITHOUT a `verifier` field
|
||||
- **THEN** the Zod options-validation throws AND no schema instance is
|
||||
returned
|
||||
|
||||
#### Scenario: DI'd verifier produces same boolean answer as direct import
|
||||
|
||||
- **WHEN** `defineSignedBitSchema(codec, { domain, verifier:
|
||||
verifyAuthoritySignature })` packs a payload and the result is
|
||||
`unpack`-ed
|
||||
- **THEN** the round-trip matches the original AND the verify path
|
||||
emits the same OTel span as the archived rewrite
|
||||
|
||||
#### Scenario: bitpacker-crypto's compiled `dist/` contains zero references to `@suaveplan/crypto`
|
||||
|
||||
- **WHEN** `bunx turbo build --filter=@suaveplan/bitpacker-crypto` runs
|
||||
- **THEN** `grep -r "@suaveplan/crypto"
|
||||
packages/bitpacker/bitpacker-crypto/dist/` returns zero matches in
|
||||
`*.js` and `*.d.ts` files
|
||||
|
||||
**Verified by:** `packages/bitpacker/bitpacker-crypto/src/signed/signed-bitschema.test.ts::"missing verifier rejects at construction time"` AND `packages/bitpacker/bitpacker-crypto/src/signed/signed-bitschema.test.ts::"pack signs via Authority under the configured domain"` AND `packages/bitpacker/bitpacker-crypto/src/signed/signed-bitschema.spec-conformance.test.ts::"signed-pack emits OTel span with domain attribute"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: MultiSignedBitSchema accepts injected verifier
|
||||
|
||||
The `defineMultiSignedBitSchema<T>(bodyCodec, options)` function SHALL
|
||||
accept a required `verifier: AuthorityVerifier` field on its options
|
||||
bundle. The primitive SHALL call `verifier(...)` for each signature
|
||||
verification instead of importing `verifyAuthoritySignature`. Wire
|
||||
format, count enforcement, `firstBadSignerIndex` reporting,
|
||||
`CRYPTO_MULTISIGN_COUNT_MISMATCH` semantics — all unchanged.
|
||||
|
||||
#### Scenario: missing `verifier` rejects at construction time
|
||||
|
||||
- **WHEN** `defineMultiSignedBitSchema(codec, { domain: D, signerCount:
|
||||
2 })` is called WITHOUT a `verifier` field
|
||||
- **THEN** the Zod options-validation throws
|
||||
|
||||
#### Scenario: DI'd verifier preserves firstBadSignerIndex semantics
|
||||
|
||||
- **WHEN** a 3-signer payload's second signature is flipped and
|
||||
`verify(bytes, [pubA, pubB, pubC])` is called with the DI'd
|
||||
`verifyAuthoritySignature`
|
||||
- **THEN** the result is `{ valid: false, firstBadSignerIndex: 1 }`
|
||||
identical to the archived rewrite
|
||||
|
||||
**Verified by:** `packages/bitpacker/bitpacker-crypto/src/multisigned/multisigned-bitschema.test.ts::"missing verifier rejects at construction time"` AND `packages/bitpacker/bitpacker-crypto/src/multisigned/multisigned-bitschema.test.ts::"verify pinpoints which signer failed"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: HashChainSchema accepts injected verifier
|
||||
|
||||
The `defineHashChainSchema<TPayload>(options)` function SHALL accept
|
||||
a required `verifier: AuthorityVerifier` field on its options bundle.
|
||||
`verifyEntry` and `verifyChain` SHALL use the DI'd verifier. All
|
||||
chain-walk, prev-hash linkage, tamper detection (`firstBadIndex`),
|
||||
pluggable hash registry behavior — all unchanged.
|
||||
|
||||
#### Scenario: missing `verifier` rejects at construction time
|
||||
|
||||
- **WHEN** `defineHashChainSchema({ domain: D, payloadCodec: c })` is
|
||||
called WITHOUT a `verifier` field
|
||||
- **THEN** the Zod options-validation throws
|
||||
|
||||
#### Scenario: chain verification detects tamper at exact index with DI'd verifier
|
||||
|
||||
- **WHEN** a 5-entry chain is built using the DI'd verifier, then
|
||||
entry-2's payload is mutated and `verifyChain` is called
|
||||
- **THEN** the result is `{ valid: false, firstBadIndex: 2 }` identical
|
||||
to the archived rewrite
|
||||
|
||||
**Verified by:** `packages/bitpacker/bitpacker-crypto/src/hashchain/hashchain-schema.test.ts::"missing verifier rejects at construction time"` AND `packages/bitpacker/bitpacker-crypto/src/hashchain/hashchain-schema.test.ts::"chain verification detects tamper at exact index"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: EncryptedBitSchema accepts injected AEAD operations
|
||||
|
||||
The `defineEncryptedBitSchema<T>(bodyCodec, options)` function SHALL
|
||||
accept a required `aead: AeadOps` field on its options bundle. The
|
||||
primitive SHALL call `aead.encrypt(...)` and `aead.decrypt(...)`
|
||||
instead of importing `aeadEncrypt` / `aeadDecrypt` directly.
|
||||
|
||||
The constants `AEAD_KEY_LENGTH = 32`, `AEAD_NONCE_LENGTH = 12`, and
|
||||
`AEAD_XCHACHA_NONCE_LENGTH = 24` SHALL be declared locally in
|
||||
`encrypted-bitschema.ts` (not imported from `@suaveplan/crypto`).
|
||||
Duplication is acceptable because these values are part of the
|
||||
bit-packer-crypto wire format.
|
||||
|
||||
The primitive SHALL import `AeadAlgorithm`, `AeadOps`, `Rng` from
|
||||
`@suaveplan/types`. Wire format `[version u8][algTag u8][nonceLen u8]
|
||||
[nonce][ciphertext + tag]` and the closed `ENCRYPTED_ALG_TAGS` enum
|
||||
remain unchanged.
|
||||
|
||||
#### Scenario: missing `aead` rejects at construction time
|
||||
|
||||
- **WHEN** `defineEncryptedBitSchema(codec, { key })` is called WITHOUT
|
||||
an `aead` field
|
||||
- **THEN** the Zod options-validation throws
|
||||
|
||||
#### Scenario: DI'd AEAD bundle preserves round-trip semantics
|
||||
|
||||
- **WHEN** `defineEncryptedBitSchema(codec, { key, aead: { encrypt:
|
||||
aeadEncrypt, decrypt: aeadDecrypt } })` packs and unpacks a payload
|
||||
- **THEN** the round-trip matches the original AND tampered ciphertext
|
||||
rejects with `CRYPTO_DECRYPT_FAILED` identical to the archived
|
||||
rewrite
|
||||
|
||||
#### Scenario: bitpacker-crypto's `package.json` lists `@suaveplan/crypto` only as devDependency
|
||||
|
||||
- **WHEN** `cat
|
||||
packages/bitpacker/bitpacker-crypto/package.json | jq -r
|
||||
'.dependencies | keys[]'` runs
|
||||
- **THEN** the output does NOT include `@suaveplan/crypto`
|
||||
- **AND** `cat packages/bitpacker/bitpacker-crypto/package.json | jq -r
|
||||
'.devDependencies | keys[]'` DOES include `@suaveplan/crypto`
|
||||
|
||||
**Verified by:** `packages/bitpacker/bitpacker-crypto/src/encrypted/encrypted-bitschema.test.ts::"missing aead rejects at construction time"` AND `packages/bitpacker/bitpacker-crypto/src/encrypted/encrypted-bitschema.test.ts::"round-trips through XChaCha20-Poly1305"` AND `packages/bitpacker/bitpacker-crypto/src/encrypted/encrypted-bitschema.test.ts::"tampered ciphertext rejects with CRYPTO_DECRYPT_FAILED"`
|
||||
|
||||
<!-- markdownlint-enable MD024 -->
|
||||
Reference in New Issue
Block a user