docs: correct ecosystem dependency direction and add integration context
Architecture docs previously referenced the hub as the authoritative source for call/identity specs. In reality, call protocol, identity, and access control come from @alkdev/operations; call graph schemas from @alkdev/flowgraph; task graph schemas from @alkdev/taskgraph; event transport from @alkdev/pubsub. The hub is a consumer of @alkdev/storage, not the other way around. Key changes: - overview.md: add Ecosystem Integration section with dependency direction diagram, What Comes From Where table, repo layer bridging pattern, and circular dependency avoidance guidance - overview.md: promote repo-layer vs operations-bridging from open question to explicit decision (CRUD in storage, bridging in consumer) - overview.md: add zero-ecosystem-dependency statement; fix taskgraph type names (TaskGraphNodeAttributes, DependencyEdge) - overview.md: fix terminology (hub is consumer, not authority) - metagraph.md: add Ecosystem Context section; replace hub references with correct ecosystem sources; fix GraphStatus/GraphBaseType enum mischaracterization (C1); unify empty-array semantics with sqlite-host (C2); clarify repo layer does NOT import operations (C3); add flowgraph canonical schema note; add versioning cross-reference to graph_types table - encrypted-data.md: reframe hub as provenance not authority; update What Lives Where table; fix standalone table advice; update references - sqlite-host.md: fix actors table description; unify empty-array semantics; contextualize hub as reference consumer; add operations identity reference
This commit is contained in:
@@ -5,22 +5,26 @@ last_updated: 2026-05-28
|
||||
|
||||
# Encrypted Data
|
||||
|
||||
Design for storing encrypted data at rest within the metagraph model. Adapts the
|
||||
hub's AES-256-GCM + PBKDF2 encryption pattern as a reusable node type and crypto
|
||||
utility.
|
||||
Design for storing encrypted data at rest within the metagraph model. Uses
|
||||
AES-256-GCM + PBKDF2 key derivation, providing a reusable node type, TypeBox
|
||||
schema, and crypto utility for any consumer that needs to store secrets.
|
||||
|
||||
## Overview
|
||||
|
||||
Sensitive data — API keys, passwords, OAuth tokens, SSH keys — must be encrypted
|
||||
at rest. The hub's `client_secrets` table stores these as encrypted JSON blobs.
|
||||
In `@alkdev/storage`, the same encryption pattern becomes a reusable utility and
|
||||
an encrypted node type, so any graph can store secrets without special table
|
||||
at rest. In `@alkdev/storage`, the encryption pattern becomes a reusable utility
|
||||
and an encrypted node type, so any graph can store secrets without special table
|
||||
definitions.
|
||||
|
||||
**Key principle**: The storage package provides the **encryption primitives and
|
||||
the schema shape**, not key management. Consumers provide the encryption key.
|
||||
This keeps the package agnostic to deployment-specific secret management.
|
||||
|
||||
**Provenance**: The encryption pattern (AES-256-GCM + PBKDF2) was originally
|
||||
implemented in the hub's `client_secrets` table and `src/crypto/mod.ts`.
|
||||
`@alkdev/storage` extracts this pattern as a general-purpose utility, independent
|
||||
of the hub's domain model.
|
||||
|
||||
## The Problem
|
||||
|
||||
The hub has `client_secrets` as a standalone table with columns like:
|
||||
@@ -113,13 +117,13 @@ graph edge rather than a foreign key.
|
||||
| `@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` |
|
||||
| Application | Key management (key ring, key rotation) | Consumer |
|
||||
| Application | Repository layer (validate schema, encrypt before insert) | Consumer |
|
||||
|
||||
## EncryptedData Schema
|
||||
|
||||
Ported from the hub's `src/crypto/mod.ts` interface, expressed as a TypeBox
|
||||
schema:
|
||||
Ported from the hub's `src/crypto/mod.ts` interface, now expressed as a TypeBox
|
||||
schema in `@alkdev/storage`:
|
||||
|
||||
```ts
|
||||
import { Type } from "@alkdev/typebox";
|
||||
@@ -232,14 +236,14 @@ because:
|
||||
- **Uniform query patterns** — All graph queries work on secret nodes without
|
||||
special code
|
||||
|
||||
**When a standalone table might be better**: If the hub needs to query "all
|
||||
active API keys" across all clients with a single indexed `WHERE` clause, a
|
||||
dedicated `api_keys` table with proper indexes is faster. The graph model
|
||||
requires traversing edges to find related secrets. For the hub's specific use
|
||||
**When a standalone table might be better**: If a consumer (like the hub) needs
|
||||
to query "all active API keys" across all clients with a single indexed `WHERE`
|
||||
clause, a dedicated `api_keys` table with proper indexes is faster. The graph
|
||||
model requires traversing edges to find related secrets. For a hub's specific use
|
||||
case (key lookup on every authenticated request), this matters. The metagraph
|
||||
pattern is optimized for flexibility, not raw key-lookup performance. The hub
|
||||
should use a standalone `api_keys` table for authentication and the metagraph
|
||||
for everything else.
|
||||
pattern is optimized for flexibility, not raw key-lookup performance. Consumers
|
||||
should use standalone tables for authentication hot paths and the metagraph for
|
||||
everything else.
|
||||
|
||||
### ED3: Password-based encryption, not raw-key encryption
|
||||
|
||||
@@ -366,9 +370,11 @@ Crypto API and `@alkdev/typebox` for the schema).
|
||||
|
||||
## References
|
||||
|
||||
- Hub crypto utility: `/workspace/@alkdev/hub/src/crypto/mod.ts`
|
||||
- Hub `client_secrets` table:
|
||||
`/workspace/@alkdev/hub/docs/architecture/storage/services.md`
|
||||
- Hub ADR-008:
|
||||
`/workspace/@alkdev/hub/docs/decisions/ADR-008-secrets-encrypted-at-rest-with-key-versioning.md`
|
||||
- Web Crypto API: https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto
|
||||
- Hub crypto utility (provenance): `/workspace/@alkdev/hub/src/crypto/mod.ts`
|
||||
- Hub `client_secrets` table (provenance):
|
||||
`/workspace/@alkdev/hub/docs/architecture/storage/services.md`
|
||||
- Hub ADR-008 (provenance):
|
||||
`/workspace/@alkdev/hub/docs/decisions/ADR-008-secrets-encrypted-at-rest-with-key-versioning.md`
|
||||
- `@alkdev/operations` AccessControl:
|
||||
`/workspace/@alkdev/operations/docs/architecture/api-surface.md`
|
||||
|
||||
Reference in New Issue
Block a user