tapimo 0.0.2 → 0.2.0

package/README.md

@@ -33,24 +33,46 @@ Install the package:
 pnpm i tapimo
 ```
 
-Compose an app with `App.create`. It returns a handler with a Web `fetch`
-method and a Node.js `listener`, so you can serve it from any runtime or
+Stateful features (webhook subscriptions, verified tokens) live in Postgres.
+Provision a database and apply migrations with the CLI:
+
+```sh
+DATABASE_URL=postgresql://… tapimo admin migrate
+```
+
+The API is composed from route groups (apps) imported from `tapimo/apps`.
+Create a base app with `App.create` and mount the apps you want:
+
+<!-- prettier-ignore -->
+```ts
+import { App, Db } from 'tapimo'
+import { data } from 'tapimo/apps'
+
+const app = App.create({
+  db: Db.postgres({ connectionString: process.env.DATABASE_URL }),
+}).route('/', data())
+```
+
+| App          | Purpose                        | Resources (non-exhaustive)             |
+| ------------ | ------------------------------ | -------------------------------------- |
+| `data()`     | Chain and indexed data reads   | Blocks, transactions, tokens, webhooks |
+| `relay()`    | Wallet relay & fee sponsorship | Relay                                  |
+| `platform()` | Tenancy and access management  | Orgs, projects, members, API keys      |
+
+The composed app exposes a Web `fetch` method, and `App.listener` adapts it
+to a Node.js request listener, so you can serve it from any runtime or
 framework:
 
 <!-- prettier-ignore -->
 ```ts
-import { App } from 'tapimo'
-
-const handler = App.create()
-
-createServer(handler.listener)                // Node.js
-Bun.serve({ fetch: handler.fetch })           // Bun
-Deno.serve({ fetch: handler.fetch })          // Deno
-app.all('*', (c) => handler.fetch(c.request)) // Elysia
-app.use(handler.listener)                     // Express
-app.use((c) => handler.fetch(c.req.raw))      // Hono
-export const GET = handler.fetch              // Next.js
-export const POST = handler.fetch             // Next.js
+createServer(App.listener(app))              // Node.js
+Bun.serve({ fetch: app.fetch })              // Bun
+Deno.serve({ fetch: app.fetch })             // Deno
+server.all('*', (c) => app.fetch(c.request)) // Elysia
+server.use(App.listener(app))                // Express
+server.use((c) => app.fetch(c.req.raw))      // Hono
+export const GET = app.fetch                 // Next.js
+export const POST = app.fetch                // Next.js
 ```
 
 ## Typed Client
@@ -114,6 +136,6 @@ token.symbol
 pnpm install        # Install dependencies
 pnpm test           # Run tests against live resources (like indexer)
 pnpm test:local     # Run tests against local resources
-pnpm app:dev        # Seed local KV (verified tokens) + run API app
-pnpm app:seed       # Seed local KV with curated verified tokens from seeds/
+pnpm dev            # Run Postgres plus the API and admin Workers
+pnpm api:seed       # Seed local KV with curated verified tokens from seeds/
 ```

package/dist/ApiKey.d.ts

@@ -1,23 +1,21 @@
 /**
- * The resolved API-key resource and the reusable credential primitives every
- * source backend shares.
+ * The resolved API-key resource and the reusable credential primitives.
  *
  * Holds the resolved {@link ApiKey} type and its {@link schema}, the token
- * format/generation ({@link generateToken}/{@link generateId}), the storage-key
- * derivation ({@link keyFor}/{@link recordPrefix}), and log {@link redact}ion.
- * These live here — not in a single source — so every `ApiKeySource` backend
- * (the built-in store, a future D1/Postgres source) issues and parses
- * byte-identical credentials and cannot drift. The persisted record/mint-input
- * shapes and provisioning (mint/list/revoke) belong to the
- * `ApiKeySource.Source` contract, which composes these primitives with its own
- * persistence.
+ * format/generation ({@link generateToken}/{@link generateId}), the
+ * storage-key derivation ({@link keyFor}/{@link recordPrefix}), and log
+ * {@link redact}ion. These live here — not in the persistence module — so
+ * issued and parsed credentials are byte-identical and cannot drift. The
+ * persisted record/mint-input shapes and provisioning (mint/list/revoke) live
+ * in `./ApiKeys.js`, which composes these primitives with the app's KV state
+ * store (`App.create({ kv })`).
  */
 import * as z from 'zod/mini';
 /** Zod schemas owned by the API-key module. */
 export declare namespace schema {
     /**
      * Canonical schema for resolved API-key metadata, and the single source of
-     * truth for the {@link ApiKey} type. `ApiKeySource` derives its persisted
+     * truth for the {@link ApiKey} type. `ApiKeys` derives its persisted
      * `Record` and `MintInput` schemas from this one, so the resolved and
      * persisted shapes cannot drift.
      */
@@ -29,6 +27,7 @@ export declare namespace schema {
         id: z.ZodMiniString<string>;
         name: z.ZodMiniOptional<z.ZodMiniString<string>>;
         orgId: z.ZodMiniString<string>;
+        projectId: z.ZodMiniOptional<z.ZodMiniString<string>>;
         rateLimits: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
             perMinute: z.ZodMiniNumber<number>;
         }, z.core.$strip>>>;
@@ -36,6 +35,8 @@ export declare namespace schema {
             "*": "*";
             "data:read": "data:read";
             "indexer:query": "indexer:query";
+            "rpc-relay:read": "rpc-relay:read";
+            "rpc-relay:sponsor": "rpc-relay:sponsor";
             "webhooks:read": "webhooks:read";
             "webhooks:write": "webhooks:write";
         }>>>;
@@ -60,6 +61,8 @@ export declare function generateToken(environment?: ApiKey['environment']): stri
 export declare function generateId(): string;
 /** Storage-key prefix under which key records are persisted, keyed by token hash. */
 export declare const recordPrefix = "apikey:";
+/** Hashes a plaintext token to its at-rest lookup hash (lowercase hex, no `0x`). */
+export declare function hash(token: string): string;
 /** Storage key under which the record for a plaintext token is persisted. */
 export declare function keyFor(token: string): string;
 //# sourceMappingURL=ApiKey.d.ts.map

package/dist/ApiKey.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ApiKey.d.ts","sourceRoot":"","sources":["../src/ApiKey.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,CAAC,MAAM,UAAU,CAAA;AAK7B,+CAA+C;AAC/C,yBAAiB,MAAM,CAAC;IACtB;;;;;OAKG;IACI,MAAM,MAAM;;;;;;;;;;;;;;;;;;qBAiBjB,CAAA;CACH;AAED,mDAAmD;AACnD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAA;AAEnD;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI3C;AAiCD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,WAAW,GAAE,MAAM,CAAC,aAAa,CAAgB,GAAG,MAAM,CAEvF;AAED,mDAAmD;AACnD,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,qFAAqF;AACrF,eAAO,MAAM,YAAY,YAAY,CAAA;AAOrC,6EAA6E;AAC7E,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5C"}
+{"version":3,"file":"ApiKey.d.ts","sourceRoot":"","sources":["../src/ApiKey.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,CAAC,MAAM,UAAU,CAAA;AAK7B,+CAA+C;AAC/C,yBAAiB,MAAM,CAAC;IACtB;;;;;OAKG;IACI,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;qBAkBjB,CAAA;CACH;AAED,mDAAmD;AACnD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAA;AAEnD;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI3C;AAiCD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,WAAW,GAAE,MAAM,CAAC,aAAa,CAAgB,GAAG,MAAM,CAEvF;AAED,mDAAmD;AACnD,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,qFAAqF;AACrF,eAAO,MAAM,YAAY,YAAY,CAAA;AAErC,oFAAoF;AACpF,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED,6EAA6E;AAC7E,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5C"}

package/dist/ApiKey.js

@@ -1,16 +1,14 @@
 /**
- * The resolved API-key resource and the reusable credential primitives every
- * source backend shares.
+ * The resolved API-key resource and the reusable credential primitives.
  *
  * Holds the resolved {@link ApiKey} type and its {@link schema}, the token
- * format/generation ({@link generateToken}/{@link generateId}), the storage-key
- * derivation ({@link keyFor}/{@link recordPrefix}), and log {@link redact}ion.
- * These live here — not in a single source — so every `ApiKeySource` backend
- * (the built-in store, a future D1/Postgres source) issues and parses
- * byte-identical credentials and cannot drift. The persisted record/mint-input
- * shapes and provisioning (mint/list/revoke) belong to the
- * `ApiKeySource.Source` contract, which composes these primitives with its own
- * persistence.
+ * format/generation ({@link generateToken}/{@link generateId}), the
+ * storage-key derivation ({@link keyFor}/{@link recordPrefix}), and log
+ * {@link redact}ion. These live here — not in the persistence module — so
+ * issued and parsed credentials are byte-identical and cannot drift. The
+ * persisted record/mint-input shapes and provisioning (mint/list/revoke) live
+ * in `./ApiKeys.js`, which composes these primitives with the app's KV state
+ * store (`App.create({ kv })`).
  */
 import { nanoid } from 'nanoid';
 import { Hash, Hex } from 'ox';
@@ -22,7 +20,7 @@ export var schema;
 (function (schema) {
     /**
      * Canonical schema for resolved API-key metadata, and the single source of
-     * truth for the {@link ApiKey} type. `ApiKeySource` derives its persisted
+     * truth for the {@link ApiKey} type. `ApiKeys` derives its persisted
      * `Record` and `MintInput` schemas from this one, so the resolved and
      * persisted shapes cannot drift.
      */
@@ -33,6 +31,7 @@ export var schema;
         id: z.string().check(z.describe('Stable key id.')),
         name: z.optional(z.string()).check(z.describe('Human-readable key name.')),
         orgId: z.string().check(z.describe('Owning organization id.')),
+        projectId: z.optional(z.string()).check(z.describe('Owning project id (`prj_…`).')),
         rateLimits: z
             .optional(z.record(z.string(), RateLimit.schema.Limit))
             .check(z.describe("Per-key quota overrides keyed by quota scope. The reserved '*' entry is the per-key default; any other key overrides that scope. Omit to inherit server config. The most specific match wins.")),
@@ -95,7 +94,7 @@ export function generateId() {
 /** Storage-key prefix under which key records are persisted, keyed by token hash. */
 export const recordPrefix = 'apikey:';
 /** Hashes a plaintext token to its at-rest lookup hash (lowercase hex, no `0x`). */
-function hash(token) {
+export function hash(token) {
     return Hash.sha256(Hex.fromString(token)).slice(2);
 }
 /** Storage key under which the record for a plaintext token is persisted. */

package/dist/ApiKey.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiKey.js","sourceRoot":"","sources":["../src/ApiKey.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ApiKey.js","sourceRoot":"","sources":["../src/ApiKey.ts"],"names":[],"mappings":"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"}

package/dist/ApiKeys.d.ts

@@ -0,0 +1,207 @@
+/**
+ * API-key persistence over the app's KV state store (`App.create({ kv })`).
+ *
+ * Records are keyed by token hash (`ApiKey.keyFor`) — the plaintext token is
+ * never stored — and validated against the scope catalog on read; unknown,
+ * corrupt, expired, or invalid records resolve to `null`. An `id → recordKey`
+ * index makes revoke-by-id O(1). The persisted {@link Record}/{@link
+ * MintInput} shapes live here (derived from `ApiKey.schema` so they cannot
+ * drift from the resolved shape), while the shared credential primitives
+ * (token format/generation, storage-key derivation, redaction) live in
+ * `./ApiKey.js`.
+ */
+import * as z from 'zod/mini';
+import * as ApiKey from './ApiKey.js';
+import type * as Store from './internal/Store.js';
+/** Zod schemas owned by the API-keys module. */
+export declare namespace schema {
+    /**
+     * Fields accepted when minting a key, and the single source of truth for the
+     * {@link MintInput} type and `mint` validation. Derived from the resolved
+     * `ApiKey.schema` (minus the generated `id`) so the scope vocabulary stays in
+     * lockstep with the resolved shape.
+     */
+    const MintInput: z.ZodMiniObject<{
+        environment: z.ZodMiniDefault<z.ZodMiniEnum<{
+            production: "production";
+            sandbox: "sandbox";
+        }>>;
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        projectId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        rateLimits: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
+            perMinute: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>>;
+        scopes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniEnum<{
+            "*": "*";
+            "data:read": "data:read";
+            "indexer:query": "indexer:query";
+            "rpc-relay:read": "rpc-relay:read";
+            "rpc-relay:sponsor": "rpc-relay:sponsor";
+            "webhooks:read": "webhooks:read";
+            "webhooks:write": "webhooks:write";
+        }>>>;
+        createdBy: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        expiresAt: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        orgId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>;
+    /**
+     * A persisted API-key record: the resolved `ApiKey.schema` plus
+     * persistence/display fields. Extending the resolved schema keeps the resolved
+     * and persisted shapes in lockstep.
+     */
+    const Record: z.ZodMiniObject<{
+        environment: z.ZodMiniDefault<z.ZodMiniEnum<{
+            production: "production";
+            sandbox: "sandbox";
+        }>>;
+        id: z.ZodMiniString<string>;
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        orgId: z.ZodMiniString<string>;
+        projectId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        rateLimits: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
+            perMinute: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>>;
+        scopes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniEnum<{
+            "*": "*";
+            "data:read": "data:read";
+            "indexer:query": "indexer:query";
+            "rpc-relay:read": "rpc-relay:read";
+            "rpc-relay:sponsor": "rpc-relay:sponsor";
+            "webhooks:read": "webhooks:read";
+            "webhooks:write": "webhooks:write";
+        }>>>;
+        createdAt: z.ZodMiniString<string>;
+        createdBy: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        expiresAt: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        tokenLast4: z.ZodMiniString<string>;
+    }, z.core.$strip>;
+}
+/**
+ * A durable API-key record as persisted. A superset of the resolved
+ * `ApiKey.ApiKey` with provisioning/display metadata. The plaintext token is
+ * never stored — records are keyed by its hash (`ApiKey.keyFor`) and carry only
+ * `tokenLast4` for display.
+ */
+export type Record = z.output<typeof schema.Record>;
+/**
+ * Fields accepted when minting a key via {@link mint}. Uses the schema's
+ * *input* type so defaulted fields (e.g. `environment`) are optional for
+ * callers — the default is applied during `mint`'s validation.
+ */
+export type MintInput = z.input<typeof schema.MintInput>;
+/** Result of {@link mint}: the persisted record and its one-time token. */
+export type MintResult = {
+    /** The persisted key record (metadata only — never the token). */
+    record: Record;
+    /** The plaintext token, shown once and unrecoverable afterward. */
+    token: string;
+};
+/**
+ * Mints a key: validates the input (e.g. rejects an unknown scope at the write
+ * boundary), persists its hashed record, and returns the record plus the
+ * one-time plaintext token (shown once, unrecoverable afterward).
+ *
+ * @param state - The KV state store holding key records.
+ * @param input - The key to mint.
+ * @returns The persisted record and its one-time token.
+ */
+export declare function mint(state: Store.State, input: MintInput): Promise<MintResult>;
+/**
+ * Resolves a plaintext API key token to its metadata, or `null`. Expiry is
+ * enforced on read — not just via the store's native TTL — so it holds on
+ * backends that evict lazily and regardless of TTL granularity.
+ *
+ * @param state - The KV state store holding key records.
+ * @param token - The presented plaintext token.
+ * @returns The resolved key metadata, or `null`.
+ */
+export declare function resolve(state: Store.State, token: string): Promise<ApiKey.ApiKey | null>;
+/**
+ * Reads a key record by id (metadata only — never the token), or `null`.
+ *
+ * @param state - The KV state store holding key records.
+ * @param id - The key id (`key_…`).
+ * @returns The record, or `null`.
+ */
+export declare function get(state: Store.State, id: string): Promise<Record | null>;
+/**
+ * Lists key records (metadata only — never tokens), newest first. Expired or
+ * catalog-invalid records are skipped.
+ *
+ * @param state - The KV state store holding key records.
+ * @param options - Optional owner filter.
+ * @returns The records.
+ */
+export declare function list(state: Store.State, options?: list.Options): Promise<readonly Record[]>;
+export declare namespace list {
+    /** Options for {@link list}. */
+    type Options = {
+        /** Restrict results to keys owned by this organization. */
+        orgId?: string | undefined;
+    };
+}
+/**
+ * Lists an organization's key records through the org index (no full scan),
+ * newest first. Dangling index entries (revoked or expired records) are
+ * skipped and lazily deleted.
+ *
+ * @param state - The KV state store holding key records.
+ * @param orgId - The owning organization id (`org_…`).
+ * @param options - Optional project filter.
+ * @returns The records.
+ */
+export declare function listByOrg(state: Store.State, orgId: string, options?: listByOrg.Options): Promise<readonly Record[]>;
+export declare namespace listByOrg {
+    /** Options for {@link listByOrg}. */
+    type Options = {
+        /** Restrict results to keys attributed to this project. */
+        projectId?: string | undefined;
+    };
+}
+/**
+ * Revokes a key by id, deleting its record and index entries.
+ *
+ * @param state - The KV state store holding key records.
+ * @param id - The key id (`key_…`).
+ * @returns Whether a matching record was deleted.
+ */
+export declare function revoke(state: Store.State, id: string): Promise<boolean>;
+/**
+ * Re-attributes a key to an organization and/or project, rewriting its record
+ * in place (same token hash) and moving the org index entry when the org
+ * changes. The backfill path for legacy keys.
+ *
+ * @param state - The KV state store holding key records.
+ * @param id - The key id (`key_…`).
+ * @param input - The attribution to apply.
+ * @returns The updated record, or `null` when the key is absent.
+ */
+export declare function attribute(state: Store.State, id: string, input: attribute.Input): Promise<Record | null>;
+export declare namespace attribute {
+    /** Attribution applied by {@link attribute}; omitted fields keep their current value. */
+    type Input = {
+        /** New owning organization id (`org_…`). */
+        orgId?: string | undefined;
+        /** New owning project id (`prj_…`). */
+        projectId?: string | undefined;
+    };
+}
+/**
+ * Rebuilds the `id` and `org` index entries for every stored record — the
+ * run-once backfill making legacy keys visible to org-scoped listing. Records
+ * themselves are never modified, so existing tokens keep resolving.
+ *
+ * @param state - The KV state store holding key records.
+ * @returns Scanned and indexed record counts.
+ */
+export declare function backfill(state: Store.State): Promise<backfill.Result>;
+export declare namespace backfill {
+    /** Result of {@link backfill}. */
+    type Result = {
+        /** Records whose index entries were written. */
+        indexed: number;
+        /** Stored records scanned (including invalid or expired ones, skipped). */
+        scanned: number;
+    };
+}
+//# sourceMappingURL=ApiKeys.d.ts.map

package/dist/ApiKeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiKeys.d.ts","sourceRoot":"","sources":["../src/ApiKeys.ts"],"names":[],"mappings":"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"}