Clean up architecture specs: remove stale references, align docs with code, improve readability
- Replace stale DD references (DD3, DD6, DD9, DD10) with proper ADR links - Fix 'Open Question 1' → OQ-01/OQ-03 cross-references - Rewrite metagraph-module.md 'Why TypeBox Modules' to describe capabilities directly instead of framing as SchemaBuilder replacement - Remove 'Transition from SchemaBuilder' section, replace with Source Structure - Clean up implementation path: strikethrough phases → status table - Fix data model diagram: remove non-existent nodeTypeId, fix EdgeType label - Align EdgeConstraints examples with actual code (add default values) - Clarify validateNode/validateEdge error behavior in docs - Align EncryptedDataSchema code example with actual implementation - Fix overview.md: correct dependency table, update current state, fix TypeBox URL - Fix forward-look.md garbled text about dbtype element migration - Fix open-questions.md: correct OQ count (4→7 open), add summary table - Update doc statuses: schema-evolution, encrypted-data, open-questions → reviewed - Update AGENTS.md to reflect current implementation state
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-05-28
|
||||
status: reviewed
|
||||
last_updated: 2026-05-30
|
||||
---
|
||||
|
||||
# Encrypted Data
|
||||
@@ -117,9 +117,9 @@ graph edge rather than a foreign key.
|
||||
| Layer | Responsibility | Package |
|
||||
| ------------------------ | --------------------------------------------------------- | ------------------------ |
|
||||
| `@alkdev/storage` graphs | `EncryptedDataSchema` (TypeBox shape) | `@alkdev/storage` |
|
||||
| `@alkdev/storage` crypto | `encrypt()`, `decrypt()`, `generateEncryptionKey()` | `@alkdev/storage` |
|
||||
| `@alkdev/storage` sqlite | Node storage (attributes contain encrypted JSON) | `@alkdev/storage/sqlite` |
|
||||
| `@alkdev/storage` repo | Validate schema, encrypt before insert (⚠️ not yet impl) | `@alkdev/storage` |
|
||||
| `@alkdev/storage` crypto | `encrypt()`, `decrypt()`, `generateEncryptionKey()` | `@alkdev/storage` |
|
||||
| `@alkdev/storage` sqlite | Node storage (attributes contain encrypted JSON) | `@alkdev/storage/sqlite` |
|
||||
| `@alkdev/storage` repo | Validate schema, encrypt on insert (⚠️ CRUD layer not yet built) | `@alkdev/storage` |
|
||||
| Application | Key management (key ring, key rotation) | Consumer |
|
||||
|
||||
## EncryptedData Schema
|
||||
@@ -131,20 +131,18 @@ schema in `@alkdev/storage`:
|
||||
import { Type } from "@alkdev/typebox";
|
||||
|
||||
export const EncryptedDataSchema = Type.Object({
|
||||
keyVersion: Type.Integer({
|
||||
minimum: 1,
|
||||
description: "Encryption key version for rotation",
|
||||
}),
|
||||
salt: Type.String({ description: "Base64-encoded 16-byte PBKDF2 salt" }),
|
||||
iv: Type.String({
|
||||
description: "Base64-encoded 12-byte AES-GCM initialization vector",
|
||||
}),
|
||||
data: Type.String({ description: "Base64-encoded AES-256-GCM ciphertext" }),
|
||||
keyVersion: Type.Integer({ minimum: 1 }),
|
||||
salt: Type.String(), // Base64-encoded 16-byte PBKDF2 salt
|
||||
iv: Type.String(), // Base64-encoded 12-byte AES-GCM initialization vector
|
||||
data: Type.String(), // Base64-encoded AES-256-GCM ciphertext
|
||||
});
|
||||
```
|
||||
|
||||
This is the same structure as the hub's `EncryptedData` interface but as a
|
||||
TypeBox schema, enabling runtime validation when inserting encrypted nodes.
|
||||
The fields contain: `keyVersion` — which encryption key version was used (enables key
|
||||
rotation), `salt` — base64-encoded 16-byte PBKDF2 salt, `iv` — base64-encoded
|
||||
12-byte AES-GCM initialization vector, `data` — base64-encoded AES-256-GCM
|
||||
ciphertext. This is the same structure as the hub's `EncryptedData` interface but
|
||||
as a TypeBox schema, enabling runtime validation when inserting encrypted nodes.
|
||||
|
||||
## Crypto Utility
|
||||
|
||||
@@ -255,18 +253,24 @@ const attributes = {
|
||||
|
||||
## Export Plan
|
||||
|
||||
The crypto module will be exported from the main `@alkdev/storage` package (no
|
||||
The crypto module is exported from the main `@alkdev/storage` package (no
|
||||
db deps):
|
||||
|
||||
```
|
||||
src/graphs/
|
||||
├── modules/metagraph.ts # Metagraph Module (BaseNode, BaseEdge, Config)
|
||||
├── crypto.ts # new: encrypt(), decrypt(), generateEncryptionKey(), EncryptedDataSchema
|
||||
└── mod.ts # re-exports all of the above
|
||||
├── modules/
|
||||
│ ├── metagraph.ts # Metagraph Module (Config, BaseNode, BaseEdge)
|
||||
│ ├── call-graph.ts # CallGraph reference Module
|
||||
│ ├── secret-graph.ts # SecretGraph reference Module (uses EncryptedDataSchema)
|
||||
│ └── index.ts # Barrel re-export
|
||||
├── bridge.ts # moduleToDbSchema, validateNode, validateEdge
|
||||
├── crypto.ts # encrypt(), decrypt(), generateEncryptionKey(), EncryptedDataSchema
|
||||
└── mod.ts # Re-exports all of the above
|
||||
```
|
||||
|
||||
This keeps the encryption utility in the zero-dep export path (it only uses Web
|
||||
Crypto API and `@alkdev/typebox` for the schema).
|
||||
The encryption utility is in the zero-dep export path (it only uses Web Crypto
|
||||
API and `@alkdev/typebox` for the schema). `SecretGraph` in `secret-graph.ts`
|
||||
composes `EncryptedDataSchema` into a node type via `Type.Composite`.
|
||||
|
||||
## Open Questions
|
||||
|
||||
|
||||
Reference in New Issue
Block a user