alkdev/storage
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Restructure identity tables: separate credential types, add peer_credentials, specify FK cascades and indexes

Browse Source 
Identity tables were derived from hub's PostgreSQL schema but simplified
without documenting what was removed or why. This restructures them for the
current auth landscape (API key + wraith SSH/cert-authority):

- ADR-049: Separate api_keys and peer_credentials tables (different lookup
  patterns, columns, lifecycles), remove Gitea columns, map hub data→metadata
- ADR-050: Extract SHA-256 vs KDF decision from inline spec text
- Add peer_credentials table for SSH key and cert-authority auth
- Specify all FK cascade behaviors within system DB (RESTRICT, CASCADE, SET NULL)
- Complete index specifications for all identity tables
- Add scope boundary section (storage owns schemas, not auth/authorization)
- Update audit_logs with credentialId+credentialType polymorphic reference
- Add 3 new open questions (OQ-33/34/35) for credential type expansion
This commit is contained in:
glm-5.1
2026-06-02 12:33:20 +00:00
parent 412ad98f11
commit ae242f33b9
5 changed files with 539 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

310
docs/architecture/sqlite-host.md
View File

@@ -1,6 +1,6 @@
---
status: draft
last_updated: 2026-06-01
last_updated: 2026-06-02
---
# SQLite Host
@@ -38,7 +38,8 @@ src/sqlite/
│ │ ├── accounts.ts # accounts table + select/insert schemas
│ │ ├── organizations.ts # organizations table + select/insert schemas
│ │ ├── organization_members.ts # org membership + select/insert schemas
│ │ ├── api_keys.ts # API keys (keypal) + select/insert schemas
│ │ ├── api_keys.ts # API key credentials + select/insert schemas
│ │ ├── peer_credentials.ts # SSH key / cert-authority credentials + select/insert schemas
│ │ ├── audit_logs.ts # audit trail + select/insert schemas
│ │ └── index.ts # barrel re-export
│ ├── metagraph/
@@ -205,86 +206,285 @@ type deletion if active graphs reference it.
## Identity Tables
Identity tables live in the **system DB** (ADR-040, ADR-041). They provide
multi-tenant authentication and authorization infrastructure. These tables are
derived from the hub's existing identity tables; the schemas are aligned but
simplified for the storage package's scope.
multi-tenant authentication and authorization infrastructure. Storage owns the
table schemas and FK constraints; it does not own authentication logic,
authorization rules, key lifecycle, or credential verification — those are
consumer concerns.
The identity schemas are derived from the hub's PostgreSQL identity tables
(ADR-049). Gitea-specific columns are removed (git hosting integration is a
consumer concern, modeled in metagraph instances or consumer metadata). The
hub's `data` JSONB columns map to `commonCols.metadata` (same extension
namespace, `_subsystem.key` convention).
### Scope Boundary
Storage's identity tables provide **persistence and structural constraints**.
Consumer concerns NOT in storage's scope:
- Key generation, hashing, and verification (keypal, wraith handle this)
- Authentication protocol flow (hub/wraith handle this)
- Authorization and scope evaluation (ACL graph + operations enforce this)
- Account lifecycle policy (when to suspend, deactivate, transfer ownership)
- Key rotation and revocation orchestration
- Session and connection management
### `accounts`
| Column | Type | Notes |
|---------------|---------------------|-------|
| commonCols | — | id, metadata, createdAt, updatedAt |
| email | text NOT NULL UNIQUE | Unique identifier |
| displayName | text | Display name |
| accessLevel | text NOT NULL DEFAULT `user` | `admin`, `user`, `service` |
| status | text NOT NULL DEFAULT `active` | `active`, `suspended`, `deactivated` |
| Column | Type | Constraints | Notes |
|-------------|---------------------|----------------------------------------|-------------------------------------------------------|
| id | text | PK | Consumer-generated UUID |
| metadata | text (JSON) | default `{}` | Extension namespace (`_subsystem.key`). Replaces hub's `data` JSONB column (ADR-049). Account preferences, profile data. |
| createdAt | integer (timestamp) | not null, default `now` | |
| updatedAt | integer (timestamp) | not null, default `now` | |
| email | text | not null, **unique** | Primary identifier. Service accounts may use deployment-configured reserved patterns. |
| displayName | text | | Display name |
| accessLevel | text | not null, default `user` | `admin`, `user`, `service` |
| status | text | not null, default `active` | `active`, `suspended`, `deactivated` |
**Indexes**: `unq_accounts_email` UNIQUE on `(email)`.
**`accessLevel` semantics**: `admin` manages all resources across
organizations. `user` manages own resources and org-scoped resources. `service`
is an automated account (LLM workers, spoke credentials, CI tokens) — no git
hosting link required.
**`status` semantics**: `active` can authenticate. `suspended` is admin-locked
(security hold). `deactivated` is user-initiated shutdown. Suspended and
deactivated accounts retain owned resources (RESTRICT FK) but cannot
authenticate.
**Indexes**: `unq_accounts_email` UNIQUE on `(email)`,
`idx_accounts_access_level` on `(accessLevel)`,
`idx_accounts_status` on `(status)`.
No `giteaUsername` column — git hosting integration is a consumer concern
(ADR-049). When needed, store git associations in `metadata` or a metagraph
instance.
### `organizations`
| Column | Type | Notes |
|----------|---------------------|-------|
| commonCols | — | id, metadata, createdAt, updatedAt |
| name | text NOT NULL UNIQUE | Organization name |
| slug | text NOT NULL UNIQUE | URL-friendly identifier |
| ownerId | text NOT NULL | Logical reference to accounts.id |
| Column | Type | Constraints | Notes |
|--------|---------------------|----------------------------------------|-------------------------------------------------|
| id | text | PK | Consumer-generated UUID |
| metadata | text (JSON) | default `{}` | Extension namespace. Replaces hub's `data` JSONB column (ADR-049). Org settings, billing data. |
| createdAt | integer (timestamp) | not null, default `now` | |
| updatedAt | integer (timestamp) | not null, default `now` | |
| name | text | not null, **unique** | Organization name |
| slug | text | not null, **unique** | URL-friendly identifier |
| ownerId | text | not null, FK → accounts.id (**RESTRICT**) | Administrative/transferable owner. Cannot delete owner account while org exists. Transfer ownership first. |
**Indexes**: `unq_organizations_name` UNIQUE on `(name)`, `unq_organizations_slug` UNIQUE on `(slug)`.
**`ownerId` semantics**: The administrative owner of the organization. This
account MUST also have `membershipLevel: 'owner'` in `organization_members`
(enforced by consumer). To change the owner, the consumer calls a transfer
ownership operation that: (1) validates the new owner has `membershipLevel:
'owner'`, (2) updates `ownerId`, (3) optionally demotes the old owner's
membership level. RESTRICT cascade prevents deleting the owner account while
the org exists.
**Indexes**: `unq_organizations_name` UNIQUE on `(name)`,
`unq_organizations_slug` UNIQUE on `(slug)`,
`idx_organizations_owner_id` on `(ownerId)`.
**Dual ownership representation**: `organizations.ownerId` and
`organization_members.membershipLevel: 'owner'` both represent ownership. The
column exists for efficient lookup (a single indexed read for "who owns this
org?") and RESTRICT FK semantics (cannot delete the owner account while the
org exists). The membership row exists for relational queries ("list all
owners of this org"). The consumer-enforced invariant is: `ownerId` always
references an account that also has `membershipLevel: 'owner'` in
`organization_members`. The consumer must maintain this invariant on
membership changes and ownership transfers.
No `giteaOrgName` column — git hosting integration is a consumer concern
(ADR-049).
### `organization_members`
| Column | Type | Notes |
|-----------------|---------------------|-------|
| commonCols | — | id, metadata, createdAt, updatedAt |
| orgId | text NOT NULL | FK → organizations.id (cascade) |
| accountId | text NOT NULL | FK → accounts.id (cascade) |
| membershipLevel | text NOT NULL | `owner`, `admin`, `member` |
| Column | Type | Constraints | Notes |
|-----------------|---------------------|----------------------------------------|--------------------------------------|
| id | text | PK | Consumer-generated UUID |
| metadata | text (JSON) | default `{}` | Extension namespace |
| createdAt | integer (timestamp) | not null, default `now` | |
| updatedAt | integer (timestamp) | not null, default `now` | |
| orgId | text | not null, FK → organizations.id (**CASCADE**) | Org deletion removes memberships |
| accountId | text | not null, FK → accounts.id (**CASCADE**) | Account deletion removes memberships |
| membershipLevel | text | not null | `owner`, `admin`, `member` |
**Unique constraint**: `(orgId, accountId)`.
**Indexes**: `idx_org_members_account_id` on `(accountId)`.
**Unique constraint**: `(orgId, accountId)` — one membership per account per org.
**`membershipLevel` semantics**: `owner` has full control including member
management. `admin` can manage projects and members. `member` can access org
resources. Distinct from `organizations.ownerId` — `membershipLevel` is
runtime access control; `ownerId` is the administrative/transferable owner.
This table is the authoritative source for org membership (ADR-045). The ACL
graph's `BelongsToEdge` is derived from it — when membership changes, the
consumer writes the SQL row first, then creates or removes the ACL edge.
**Indexes**: `unq_org_members_org_account` UNIQUE on `(orgId, accountId)`,
`idx_org_members_account_id` on `(accountId)`,
`idx_org_members_org_id` on `(orgId)`.
### `api_keys`
| Column | Type | Notes |
|------------|---------------------|-------|
| commonCols | — | id, metadata, createdAt, updatedAt |
| ownerId | text NOT NULL | Logical reference to accounts.id |
| keyHash | text NOT NULL UNIQUE | SHA-256 hash (never stores raw key) |
| name | text | Human-readable key label |
| enabled | integer NOT NULL DEFAULT 1 | Disable without revoking |
| expiresAt | integer (timestamp) | When the key expires (null = never) |
| revokedAt | integer (timestamp) | When revoked (null = active) |
API key credentials for bearer token authentication. The client sends a raw
key; the consumer hashes it and looks up by `keyHash`. Storage does not
perform hashing or verification — that is a consumer concern (keypal, hub).
**Indexes**: `unq_api_keys_key_hash` UNIQUE on `(keyHash)`, `idx_api_keys_owner_id` on `(ownerId)`.
| Column | Type | Constraints | Notes |
|------------|---------------------|----------------------------------------|------------------------------------------------------|
| id | text | PK | Consumer-generated UUID |
| metadata | text (JSON) | default `{}` | Extension namespace. Scope data: `metadata.scopes` (`string[]`), `metadata.resources` (`Record<string, string[]>`), `metadata.tags` (`string[]`). Consumer provides the adapter (e.g., `HubKeyStorage` for keypal). Scopes remain in metadata rather than as native columns because scope schemas vary by consumer — keypal uses colon-separated hierarchies, other consumers may differ. |
| createdAt | integer (timestamp) | not null, default `now` | |
| updatedAt | integer (timestamp) | not null, default `now` | |
| ownerId | text | not null, FK → accounts.id (**CASCADE**) | Account deletion removes API keys |
| keyHash | text | not null, **unique** | SHA-256 hash of raw key. Never stores raw key. |
| name | text | | Human-readable key label |
| enabled | integer | not null, default 1 | Immediate disable switch (1 = enabled, 0 = disabled) |
| expiresAt | integer (timestamp) | | When the key expires (null = never) |
| revokedAt | integer (timestamp) | | When the key was revoked (null = active). Permanent. |
| rotatedToId | text | | Self-reference to `api_keys.id` — the key that replaced this one (null if not rotated). |
| lastUsedAt | integer (timestamp) | | Last authentication time. Null if never used. |
Keypal scope data is stored in `metadata` (`metadata.scopes`, `metadata.resources`).
The hub provides a `HubKeyStorage` adapter that reads/writes this table to
implement keypal's `Storage` interface.
**Key lifecycle states**: enabled+not expired = active. enabled+expired =
rejected. disabled = rejected regardless of expiration. revoked = permanently
disabled regardless of enabled/expiry.
**Rotation**: When a key is rotated, the consumer creates a new `api_keys` row
and sets the old key's `rotatedToId` to the new key's id. The old key's
`revokedAt` is set at the same time. This provides an audit trail of key
rotation without requiring a separate rotation history table.
**SHA-256 rationale**: API keys are high-entropy machine-generated strings
(128-bit+). Brute-force against SHA-256 is infeasible for such inputs. Slow
KDFs (bcrypt, Argon2) are unnecessary for machine keys — they add latency
without meaningful security improvement. (ADR-050)
**Indexes**: `unq_api_keys_key_hash` UNIQUE on `(keyHash)`,
`idx_api_keys_owner_id` on `(ownerId)`,
`idx_api_keys_enabled` on `(enabled)`,
`idx_api_keys_active` on `(ownerId)` WHERE `revokedAt IS NULL AND enabled = 1`
### `peer_credentials`
SSH key and certificate-authority credentials for wraith transport
authentication. The client presents an Ed25519 public key or OpenSSH
certificate; the consumer validates against the stored fingerprint. Storage
does not perform SSH authentication — that is a consumer concern (wraith,
hub).
| Column | Type | Constraints | Notes |
|-----------------|---------------------|----------------------------------------|------------------------------------------------------|
| id | text | PK | Consumer-generated UUID |
| metadata | text (JSON) | default `{}` | Extension namespace. Cert data: `metadata.principals` (`string[]`), `metadata.restrictions` (`string[]`), `metadata.caFingerprint` (`string`, for cert-authority entries only). |
| createdAt | integer (timestamp) | not null, default `now` | |
| updatedAt | integer (timestamp) | not null, default `now` | |
| ownerId | text | not null, FK → accounts.id (**CASCADE**) | Account deletion removes peer credentials |
| credentialType | text | not null | `ssh_key`, `cert_authority` |
| fingerprint | text | not null, **unique** | Ed25519 key fingerprint (SHA-256, OpenSSH format) |
| publicKeyData | text | not null | Full public key in OpenSSH format (`ssh-ed25519 AAAA...`) |
| name | text | | Human-readable label |
| enabled | integer | not null, default 1 | Immediate disable switch |
| expiresAt | integer (timestamp) | | When the credential expires (null = never). Certificates carry expiry; standalone keys typically don't. |
| revokedAt | integer (timestamp) | | When the credential was revoked (null = active). |
**`credentialType` semantics**: `ssh_key` is an individual public key. The
consumer verifies the key against known fingerprints. `cert_authority` is a
trusted CA public key. The consumer validates certificates signed by this CA
against the stored fingerprint. Both types share the same lookup pattern
(present fingerprint → find by fingerprint → check owner + enable + expiry +
revocation), which is why they share a table.
**Adding new credential types** (ADR-049): Credential types sharing the same
lookup column as `peer_credentials` (fingerprint-based) add a new
`credentialType` value to this table. Credential types requiring different
lookup columns warrant their own table. (OQ-33) Current types assume Ed25519
only; additional SSH key types may require `credentialType` expansion.
**Fingerprint format**: OpenSSH SHA-256 fingerprint (base64, no prefix). Used
for lookup during SSH authentication. The `publicKeyData` column stores the
full key for reconstruction/verification when needed.
**Indexes**: `unq_peer_credentials_fingerprint` UNIQUE on `(fingerprint)`,
`idx_peer_credentials_owner_id` on `(ownerId)`,
`idx_peer_credentials_credential_type` on `(credentialType)`,
`idx_peer_credentials_active` on `(ownerId)` WHERE `revokedAt IS NULL AND enabled = 1`
### `audit_logs`
| Column | Type | Notes |
|----------|---------------------|-------|
| commonCols | — | id, metadata, createdAt, updatedAt |
| action | text NOT NULL | `created`, `revoked`, `rotated`, `login`, `access_denied` |
| ownerId | text NOT NULL | Logical reference to accounts.id |
| keyId | text | Logical reference to api_keys.id (nullable) |
| orgId | text | Logical reference to organizations.id (nullable) |
| details | text (JSON) | Action-specific context |
Append-only audit trail for security-relevant events. The consumer (hub)
writes entries for key operations, authentication events, membership changes,
and other auditable actions. The consumer is responsible for reading and
displaying audit data.
**Indexes**: `idx_audit_logs_owner_id` on `(ownerId)`, `idx_audit_logs_action` on `(action)`, `idx_audit_logs_created_at` on `(createdAt)`.
| Column | Type | Constraints | Notes |
|----------------|---------------------|----------------------------------------|------------------------------------------------------|
| id | text | PK | Consumer-generated UUID |
| metadata | text (JSON) | default `{}` | Extension namespace. Session context: `metadata.sessionId` (when relevant). |
| createdAt | integer (timestamp) | not null, default `now` | |
| updatedAt | integer (timestamp) | not null, default `now` | |
| action | text | not null | `created`, `revoked`, `rotated`, `enabled`, `disabled`, `login`, `access_denied` |
| ownerId | text | not null, FK → accounts.id (**RESTRICT**) | The identity performing the action. RESTRICT prevents account deletion when audit entries exist — deactivate instead. |
| credentialId | text | | Logical reference to api_keys.id or peer_credentials.id (nullable — not all events are credential-related). |
| credentialType | text | | `api_key`, `peer_credential`, or null. Discriminator for `credentialId` — tells the consumer which table to look up. |
| orgId | text | FK → organizations.id (**SET NULL**) | Organization context. Null for personal actions. Set null on org deletion to preserve audit trail. |
| details | text (JSON) | | Action-specific context (IP, user agent, scope changes, etc.) |
**`action` enum is extensible**: The initial set covers API key operations
and basic auth events. Additional actions for account, membership, and
organization lifecycle events (e.g., `account_created`, `membership_added`,
`org_created`) should be added by consumers as those features are implemented.
**`credentialId` + `credentialType` polymorphic reference**: Replaces the
previous `keyId` column (API key only). The pair allows audit entries to
reference either credential table. No FK constraint — the consumer resolves
the table based on `credentialType` (ADR-049).
**`orgId` FK with SET NULL**: Unlike `credentialId` (polymorphic, no single
target table), `orgId` always references `organizations.id` within the same
system.db. A real FK with `SET NULL` preserves the audit trail on org deletion
(nulling the org reference without deleting the audit entry) while enforcing
referential integrity at the database level rather than relying on consumer
discipline.
**Indexes**: `idx_audit_logs_owner_id` on `(ownerId)`,
`idx_audit_logs_credential_id` on `(credentialId)`,
`idx_audit_logs_action` on `(action)`,
`idx_audit_logs_created_at` on `(createdAt)`,
`idx_audit_logs_org_id` on `(orgId)`.
### FK Cascade Behavior (System DB)
All identity table FKs are intra-database (same system.db file). Real
constraints apply, not logical references.
| Relationship | onDelete | Rationale |
|-------------|----------|-----------|
| organizations.ownerId → accounts.id | RESTRICT | Cannot delete owner account while org exists. Transfer ownership first. |
| organization_members.orgId → organizations.id | CASCADE | Org deletion removes memberships |
| organization_members.accountId → accounts.id | CASCADE | Account deletion removes memberships |
| api_keys.ownerId → accounts.id | CASCADE | Account deletion removes API keys |
| peer_credentials.ownerId → accounts.id | CASCADE | Account deletion removes peer credentials |
| audit_logs.ownerId → accounts.id | RESTRICT | Audit integrity — deactivate accounts instead of deleting. Preserves accountability. |
| audit_logs.orgId → organizations.id | SET NULL | Org deletion preserves audit trail (org reference nulled, entry retained). |
Polymorphic references (no FK, consumer resolves):
`audit_logs.credentialId` → `api_keys.id` or `peer_credentials.id`
(disambiguated by `audit_logs.credentialType`).
Cross-DB logical references (no FK, different database file):
`graphs.ownerId` → `accounts.id`, `graphs.projectId` → project identity
(ADR-042). Consumer enforces referential integrity at application layer.
## Relations
### System DB Relations
- **organizations → organization_members**: one-to-many
- **accounts → organization_members**: one-to-many
- **accounts → organizations**: one-to-many (via `organizations.ownerId`)
- **accounts → organization_members**: one-to-many (via `organization_members.accountId`)
- **accounts → api_keys**: one-to-many (via `api_keys.ownerId`)
- **accounts → peer_credentials**: one-to-many (via `peer_credentials.ownerId`)
- **accounts → audit_logs**: one-to-many (via `audit_logs.ownerId`)
- **organizations → organization_members**: one-to-many (via `organization_members.orgId`)
### Tenant DB Relations
@@ -301,7 +501,7 @@ implement keypal's `Storage` interface.
### `createSystemDatabase(client)`
Creates a Drizzle database instance with the identity schema (accounts,
organizations, organization_members, api_keys, audit_logs) attached.
organizations, organization_members, api_keys, peer_credentials, audit_logs) attached.
```ts
import { createSystemDatabase } from "@alkdev/storage/sqlite";
@@ -346,7 +546,9 @@ db.transaction((tx) => {
| [038](decisions/038-sqlite-first-pg-removed.md) | SQLite-first, PG removed | Single database host |
| [039](decisions/039-honker-as-sqlite-extension.md) | Honker as SQLite extension | DB + pub/sub + queues in one file |
| [040](decisions/040-system-db-tenant-db.md) | System DB + tenant DB | Identity in system.db, graphs in tenant-{orgId}.db |
| [041](decisions/041-identity-tables-in-storage.md) | Identity tables in storage | accounts, organizations, api_keys, audit_logs |
| [041](decisions/041-identity-tables-in-storage.md) | Identity tables in storage | accounts, organizations, api_keys, peer_credentials, audit_logs |
| [049](decisions/049-identity-schema-restructuring.md) | Identity schema restructuring | Separate credential tables, remove Gitea, data→metadata, FK cascades |
| [050](decisions/050-sha256-for-api-key-hashing.md) | SHA-256 for API keys | Fast hash for high-entropy machine keys, not slow KDF |
| [042](decisions/042-scoping-columns-on-graphs.md) | Scoping columns on graphs | `ownerId`, `projectId` on `graphs` table |
| [043](decisions/043-graph-type-scope.md) | Graph type scope | `system` / `tenant` / `user` scope on `graph_types` |
| [044](decisions/044-drizzle-honker-adapter.md) | Drizzle-Honker adapter | ~100-line session adapter, POC validated |