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:
2026-05-28 14:25:16 +00:00
parent bb544469fd
commit 33a5b0816d
4 changed files with 229 additions and 58 deletions

View File

@@ -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`