---
id: drift/crypto-module
name: Port and adapt crypto utility from hub reference implementation
status: pending
depends_on:
  - drift/metagraph-module
scope: narrow
risk: low
impact: component
level: implementation
---

## Description

Port the encryption utility from the hub's proven reference implementation at `/workspace/@alkdev/hub/src/crypto/mod.ts` to `src/graphs/crypto.ts` in `@alkdev/storage`. This is a copy-and-adapt task — the crypto logic is already working and tested in the hub. The port requires these adaptations:

1. **Replace `interface EncryptedData` with `EncryptedDataSchema`** — the hub uses a plain TypeScript interface; storage uses a TypeBox schema (`Type.Object`) so it can be used for runtime validation and composed into `SecretNode` attributes. Add `type EncryptedData = Static<typeof EncryptedDataSchema>` as the type alias.

2. **Remove code comments** — per ADR-007, `@alkdev/storage` has no comments in code. The hub has JSDoc comments which should be stripped.

3. **Keep `@std/encoding` imports** — `encodeBase64` and `decodeBase64` are the same Deno standard library module the project already uses.

4. **No other changes to crypto logic** — AES-256-GCM, PBKDF2 with SHA-256, key versioning (v1 = 100k iterations), salt/IV generation, error message — all identical to the hub version.

The module exports to `src/graphs/crypto.ts` (zero db deps, per the spec's export plan).

## Acceptance Criteria

- [ ] `src/graphs/crypto.ts` exists, adapted from `/workspace/@alkdev/hub/src/crypto/mod.ts`
- [ ] Exports: `encrypt`, `decrypt`, `generateEncryptionKey`, `EncryptedDataSchema`, `type EncryptedData = Static<typeof EncryptedDataSchema>`
- [ ] `EncryptedDataSchema` is `Type.Object` (not a plain interface) with fields: `keyVersion` (`Type.Integer({ minimum: 1 })`), `salt` (`Type.String()`), `iv` (`Type.String()`), `data` (`Type.String()`)
- [ ] `encrypt()`, `decrypt()`, `generateEncryptionKey()` are functionally identical to the hub version
- [ ] No code comments (per ADR-007)
- [ ] Key versioning: v1 uses 100,000 PBKDF2 iterations (same as hub)
- [ ] Error message on decrypt failure: `"Decryption failed: Invalid data or key"` (same as hub, no information leakage)
- [ ] No external crypto dependencies — only `crypto.subtle` (Web Crypto API) and `@std/encoding`
- [ ] `src/graphs/mod.ts` re-exports from `crypto.ts`
- [ ] `deno check mod.ts` passes

## References

- **Reference implementation**: `/workspace/@alkdev/hub/src/crypto/mod.ts` — copy and adapt from this
- docs/architecture/encrypted-data.md — spec for EncryptedDataSchema, key versioning, export plan
- docs/architecture/decisions/025-password-based-encryption-pbkdf2.md
- docs/architecture/decisions/026-application-managed-key-ring.md
- docs/architecture/decisions/027-no-key-rotation-utility.md
- docs/architecture/decisions/007-no-comments-in-code.md

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion