@domainkit/capsuledb 0.1.1 → 0.9.0

package/README.md

@@ -1,11 +1,113 @@
 # `@domainkit/capsuledb`
 
-Optional PostgreSQL persistence for DomainKit's Effect-first managed-DNS authorization lifecycle.
+DomainKit's `Storage` on PostgreSQL, as one declarative [CapsuleDB](https://github.com/aryasaatvik/CapsuleDB)
+capsule. Install it under `DomainKit.layer` and the whole durable lifecycle — provider
+authorizations, connections, attachments, interactive-flow continuations, plan/approval/receipt
+attempts, and observed readiness — lives in your database, scoped to your tenants.
 
-The host owns and supplies the exact `SqlClient`, credential encryption, identity and tenant
-policy, stable owner/domain bindings, audit, routes, and consent. The package exposes only semantic
-Effect services. It does not export tables, rows, queries, an ORM adapter, or a Promise-first API.
+The host owns the `SqlClient` and its lifetime. This package owns its own tables and never exposes
+rows, queries, or a raw client.
 
-This package is the published PostgreSQL persistence implementation for DomainKit. Its development
-dependency pins the reviewed CapsuleDB Git SHA; that pin is excluded from the packed runtime
-dependency graph.
+## Install
+
+```sh
+bun add @domainkit/capsuledb capsuledb @effect/sql-pg
+```
+
+## Wire it up
+
+```ts
+import { Config, Layer } from "effect";
+import { PgClient } from "@effect/sql-pg";
+import { Cloudflare, Custody, DomainKit, Vercel } from "domainkit";
+import { PgStorage } from "@domainkit/capsuledb";
+
+export const DomainKitLive = DomainKit.layer({
+  providers: [
+    Cloudflare.provider({
+      oauth: {
+        clientId: Config.string("CF_CLIENT_ID"),
+        clientSecret: Config.redacted("CF_CLIENT_SECRET"),
+      },
+    }),
+    Vercel.provider(),
+  ],
+}).pipe(
+  // `provideMerge`, not `provide`: `domainkit/server`'s handlers read attempts and receipts
+  // straight from Storage, so the layer they are given has to still carry it.
+  Layer.provideMerge(Layer.mergeAll(PgStorage.layer(), Custody.layerConfig())),
+  Layer.provide(PgClient.layerConfig({ url: Config.redacted("DATABASE_URL") })),
+);
+```
+
+`PgStorage.layer()` prepares at boot: it creates CapsuleDB's ledger, applies pending migrations, and
+only then provides `Storage`. A capsule service can never observe a database whose tables are
+missing.
+
+`Custody.layerConfig()` reads `DOMAINKIT_CUSTODY_KEY` and seals every provider credential before it
+reaches a row. Swap it for a KMS with `Custody.layerFromAsync`; there is no plaintext mode, and this
+package never sees one.
+
+## Or emit the SQL and assert at boot
+
+If your migrations are yours to run, take the SQL instead:
+
+```sh
+capsuledb emit \
+  --module ./node_modules/@domainkit/capsuledb/dist/index.mjs \
+  --export capsule \
+  --dialect postgres \
+  --out ./drizzle
+```
+
+That writes CapsuleDB's ledger DDL, the capsule's migration, and a readiness row, plus a
+`capsuledb.emit.json` index naming the files it owns. Apply them with your own pipeline, then boot
+in assert mode:
+
+```ts
+PgStorage.layer({ mode: "assert" });
+```
+
+Assert mode applies nothing and fails unless the database already matches the capsule, so a missed
+migration is a boot failure rather than a runtime surprise. `capsuledb check` compares an emitted
+folder against the current capsule in CI.
+
+## Tables
+
+| Table                      | Key                               | Holds                                                             |
+| -------------------------- | --------------------------------- | ----------------------------------------------------------------- |
+| `domainkit_authorizations` | `id`                              | provider grant, capabilities, revocation state, sealed credential |
+| `domainkit_connections`    | `id`                              | the principal-facing handle over one authorization                |
+| `domainkit_attachments`    | `id`, unique `(owner_id, domain)` | domain, zone, provider target                                     |
+| `domainkit_continuations`  | `id`                              | interactive-flow state with a TTL                                 |
+| `domainkit_attempts`       | `id`                              | plan, approval, receipt, status, lease, failure                   |
+| `domainkit_readiness`      | `(owner_id, domain)`              | latest observation, per-requirement evidence, backoff             |
+
+Readiness is keyed by domain rather than by attachment, so a host observing public DNS alone gets
+the same row; `attachment_id` links the attachment when one exists and is cleared when it is
+removed.
+
+Every table carries `owner_id`, and every query filters by the `Principal.Service` your host provides, so a
+row belonging to another tenant reads as absent. No foreign keys are declared, to your tables or
+between these; add the ones you want in the emitted SQL.
+
+`PgStorage.layer({ prefix })` renames the tables. The prefix is part of the physical layout: it
+changes the rendered DDL and the migration checksum, so fix it before the first deploy and never
+change it after. `registryPrefix` does the same for CapsuleDB's own ledger tables and must match
+`capsuledb emit --prefix`.
+
+## What it guarantees
+
+- Aggregate transitions — approve, claim, complete, fail, capability promotion, credential
+  replacement — run in one transaction over a `FOR UPDATE` row.
+- A continuation is consumed by `DELETE ... RETURNING`, so a replayed OAuth callback fails
+  `NotFound` instead of connecting twice.
+- Revocation is two-phase: mark `pending`, call the provider outside the transaction, then delete
+  the row only while it still holds the credential that was revoked. A crash in between, or a
+  refresh that rotated the credential mid-revoke, leaves a row `recoverRevocations` finishes later,
+  so a newly issued credential is never orphaned at the provider.
+- `withLock` takes a session advisory lock on a reserved connection and fails `Busy` rather than
+  waiting, so a credential refresh single-flights without holding a transaction across an HTTP call.
+
+The package passes `Testing.conformance.storage` from `domainkit/testing`, the same suite the
+in-memory implementation passes.

package/dist/index.d.mts

@@ -1,60 +1,29 @@
-import { Context, Effect, Schema } from "effect";
-import { ManagedDnsConnections } from "domainkit";
+import { Capsule, Registry, Schema } from "capsuledb";
+import { Storage } from "domainkit";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
-declare namespace custody_d_exports {
-  export { Credential, Error$1 as Error, Interface$1 as Interface, Service$1 as Service };
+import * as Layer from "effect/Layer";
+declare namespace PgStorage_d_exports {
+  export { Options, layer };
 }
-/** Secret token material; credential expiry remains ordinary lifecycle metadata. */
-type Credential = Omit<ManagedDnsConnections.StoredCredential, "expiresAt">;
-declare const Error_base$1: Schema.Class<Error$1, Schema.TaggedStruct<"CredentialCustodyError", {
-  readonly message: Schema.String;
-  readonly operation: Schema.String;
-  readonly retry: Schema.Literals<readonly ["never", "after-user-action", "safe", "unknown"]>;
-}>, import("effect/Cause").YieldableError>;
-declare class Error$1 extends Error_base$1 {}
-interface Interface$1 {
-  readonly open: (ciphertext: string) => Effect.Effect<Credential, Error$1>;
-  readonly seal: (credential: Credential) => Effect.Effect<string, Error$1>;
+interface Options {
+  /** Table prefix. Default `domainkit`. Part of the physical layout; immutable after first deploy. */
+  readonly prefix?: string;
+  /** `prepare` (default) migrates at boot; `assert` expects the host applied `capsuledb emit` output. */
+  readonly mode?: "prepare" | "assert";
+  /**
+   * Prefix for CapsuleDB's own ledger tables; default `capsuledb`. Set it only to match a prefix a
+   * host already uses for other capsules, and pass the same value to `capsuledb emit --prefix`.
+   */
+  readonly registryPrefix?: string;
 }
-declare const Service_base$1: Context.ServiceClass<Service$1, "@domainkit/capsuledb/CredentialCustody", Interface$1>;
-/** Host-owned encryption boundary. DomainKit never receives keys or stores plaintext. */
-declare class Service$1 extends Service_base$1 {}
-declare namespace host_bindings_d_exports {
-  export { DomainReference, Error, Interface, OwnerReference, Service };
-}
-declare const Error_base: Schema.Class<Error, Schema.TaggedStruct<"HostBindingError", {
-  readonly message: Schema.String;
-  readonly operation: Schema.String;
-  readonly retry: Schema.Literals<readonly ["never", "after-user-action", "safe", "unknown"]>;
-}>, import("effect/Cause").YieldableError>;
-declare class Error extends Error_base {}
-interface OwnerReference {
-  readonly ownerReference: string;
-}
-interface DomainReference extends OwnerReference {
-  readonly domainReference: string;
-}
-interface Interface {
-  /** Resolve a durable host owner reference without capturing request identity. */
-  readonly owner: (ownerId: string) => Effect.Effect<OwnerReference, Error>;
-  /** Resolve a host domain reference inside the caller's active transaction context. */
-  readonly domain: (input: {
-    readonly domain: string;
-    readonly ownerId: string;
-  }) => Effect.Effect<DomainReference, Error>;
-  /** Project an opaque stored owner reference back to DomainKit's semantic owner id. */
-  readonly ownerId: (ownerReference: string) => Effect.Effect<string, Error>;
-}
-declare const Service_base: Context.ServiceClass<Service, "@domainkit/capsuledb/HostBindings", Interface>;
-/** Stateless host mapping for tenant/domain foreign-key references. */
-declare class Service extends Service_base {}
+declare const layer: (options?: Options) => Layer.Layer<Storage.Service, Registry.RegistryRuntimeError, SqlClient.SqlClient>;
 //#endregion
-//#region src/persistence.d.ts
-/** PostgreSQL-only authorization lifecycle capsule. The host must prepare its registry at startup. */
-declare const capsule: Effect.Effect<import("capsuledb").Capsule<ManagedDnsConnections.Service, never, Service$1 | Service | SqlClient.SqlClient>, import("capsuledb").InvalidDefinition | import("capsuledb").CapsuleDefinitionError, never>;
+//#region src/capsule.d.ts
+/** The capsule under the default `domainkit` prefix. `capsuledb emit --export capsule` reads this. */
+declare const capsule: Capsule.Capsule<Storage.Service, never, SqlClient.SqlClient>;
 //#endregion
 //#region src/index.d.ts
 declare const VERSION: string;
 //#endregion
-export { custody_d_exports as CredentialCustody, host_bindings_d_exports as HostBindings, VERSION, capsule };
+export { PgStorage_d_exports as PgStorage, VERSION, capsule };
 //# sourceMappingURL=index.d.mts.map