@hardkas/artifacts 0.8.20-alpha → 0.9.0-alpha

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +31 -31
  2. package/dist/index.d.ts +1458 -1
  3. package/dist/index.js +189 -4
  4. package/package.json +3 -3
package/README.md CHANGED
@@ -1,44 +1,44 @@
1
1
  # `@hardkas/artifacts`
2
2
 
3
- The Artifacts engine is the cryptographic heart of HardKAS. It ensures that every plan, signature, and transaction receipt is content-addressed, deterministic, and immutable.
3
+ The artifacts package is the persistence and verification layer for HardKas transaction plans, signed transactions, receipts, snapshots, and related local records.
4
4
 
5
- ## 1. Deterministic Hashing Pipeline
5
+ ## 1. Deterministic Hashing
6
6
 
7
- HardKAS does not hash raw JSON strings. It hashes the *semantic meaning* of an artifact. Two artifacts generated on different OS platforms, or with different `hardkasVersion` metadata, must hash to the exact same `contentHash`.
7
+ HardKas artifacts are intended to be content-addressed and replayable. Verification recalculates canonical content and compares it with the stored metadata.
8
8
 
9
- ### Flow: Canonicalization
10
- 1. **Semantic Exclusion:** Metadata fields (like `createdAt`, `hardkasVersion`, `os`) are aggressively stripped from the payload.
11
- 2. **Key Sorting:** Object keys are sorted recursively.
12
- - **CRITICAL INVARIANT:** Sorting must use strict byte-level comparison. `localeCompare` is explicitly forbidden to prevent cross-platform determinism failures.
13
- 3. **Data Types:** `BigInt` values are explicitly serialized to base-10 strings to prevent JSON truncation.
14
- 4. **Unicode Normalization:** All string values are normalized using NFC.
15
- 5. **Hashing:** The canonical JSON string is passed through SHA-256.
9
+ The hashing pipeline should preserve these invariants:
16
10
 
17
- ## 2. Path Traversal & Workspace Boundaries
11
+ - Metadata such as timestamps and tool versions must not change the semantic hash.
12
+ - Object keys are sorted deterministically.
13
+ - BigInt values are serialized as decimal strings.
14
+ - Strings are normalized consistently.
15
+ - Hashing uses the canonical payload, not raw JSON formatting.
18
16
 
19
- HardKAS operates strictly within the `.hardkas/` directory.
17
+ ## 2. Workspace Boundaries
20
18
 
21
- ### Flow: Secure Read/Write
22
- Any read or write to the artifact store (`.hardkas/artifacts/`) passes through a strict path normalizer:
23
- 1. The requested path is resolved using `path.resolve()`.
24
- 2. The engine verifies that the resolved path begins exactly with the absolute path of `.hardkas/artifacts/`.
19
+ Artifact reads and writes should stay inside the workspace-controlled artifact area. Callers must not be able to use paths such as `../..` to escape into unrelated filesystem locations.
25
20
 
26
- ### Variant: Traversal Attempt
27
- If an artifact reference attempts to break out of the workspace (e.g., `../../../etc/passwd`):
28
- 1. The verification engine throws a `PATH_TRAVERSAL_ATTEMPT` exception.
29
- 2. The violation is logged securely without leaking the underlying system path.
30
- 3. The artifact read is hard-aborted.
21
+ The expected secure flow is:
31
22
 
32
- ## 3. Lineage Verification (Replay Engine)
23
+ 1. Resolve the requested path.
24
+ 2. Compare it against the allowed artifact/workspace root.
25
+ 3. Abort before reading or writing if the resolved path escapes that root.
33
26
 
34
- Artifacts form a cryptographic Directed Acyclic Graph (DAG) via a `causationId` field.
27
+ ## 3. Lineage Verification
35
28
 
36
- ### Flow: Strict Verification (`--strict`)
37
- When running `hardkas verify --strict`:
38
- 1. Every artifact in `.hardkas/artifacts/` is loaded into memory.
39
- 2. Its canonical hash is recalculated and compared against its filename.
40
- 3. The engine follows the `causationId` pointers: `Receipt` -> `SignedTx` -> `TxPlan`.
41
- 4. If a parent artifact is missing, or its hash has changed, the verification immediately fails with `LINEAGE_BROKEN`.
29
+ Transaction artifacts form a chain:
42
30
 
43
- ### Variant: Relaxed Verification
44
- When querying artifacts interactively (e.g., `hardkas query artifacts list`), the engine skips full lineage recalculation for speed, relying on SQLite indexing. If a discrepancy is found later, the `Query Store` will flag the artifact as `ORPHANED` rather than halting the entire workspace.
31
+ ```text
32
+ TxPlan -> SignedTx -> Receipt
33
+ ```
34
+
35
+ The relationship is stored through artifact identifiers, content hashes, and lineage metadata. A strict verifier should fail if a parent artifact is missing, mutated, or inconsistent with the child that references it.
36
+
37
+ CLI checks:
38
+
39
+ ```bash
40
+ hardkas verify --deep
41
+ hardkas artifact verify <artifact-path> --strict
42
+ ```
43
+
44
+ Interactive queries can use the SQLite query store for speed, but the query store is only a projection. Deep verification should always go back to the artifact data.