tapimo 0.0.2 → 0.1.0

package/README.md

@@ -33,15 +33,24 @@ Install the package:
 pnpm i tapimo
 ```
 
+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
+```
+
 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
 framework:
 
 <!-- prettier-ignore -->
 ```ts
-import { App } from 'tapimo'
+import { App, Db } from 'tapimo'
 
-const handler = App.create()
+const handler = App.create({
+  db: Db.postgres({ connectionString: process.env.DATABASE_URL }),
+})
 
 createServer(handler.listener)                // Node.js
 Bun.serve({ fetch: handler.fetch })           // Bun

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.
      */
@@ -36,6 +34,7 @@ export declare namespace schema {
             "*": "*";
             "data:read": "data:read";
             "indexer:query": "indexer:query";
+            "rpc-relay": "rpc-relay";
             "webhooks:read": "webhooks:read";
             "webhooks:write": "webhooks:write";
         }>>>;
@@ -60,6 +59,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;;;;;;;;;;;;;;;;;;;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;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.
      */
@@ -95,7 +93,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,139 @@
+/**
+ * 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>>;
+        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": "rpc-relay";
+            "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>;
+        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": "rpc-relay";
+            "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>;
+/**
+ * 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;
+    };
+}
+/**
+ * Revokes a key by id, deleting its record and index entry.
+ *
+ * @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>;
+//# 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":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,CAAC,MAAM,UAAU,CAAA;AAE7B,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,KAAK,KAAK,MAAM,qBAAqB,CAAA;AAEjD,gDAAgD;AAChD,yBAAiB,MAAM,CAAC;IACtB;;;;;OAKG;IACI,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;qBASpB,CAAA;IAEF;;;;OAIG;IACI,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;qBAKjB,CAAA;CACH;AAED;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAA;AAEnD;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,SAAS,CAAC,CAAA;AAExD,2EAA2E;AAC3E,MAAM,MAAM,UAAU,GAAG;IACvB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAkCpF;AAED;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,CAE9F;AAED;;;;;;;GAOG;AACH,wBAAsB,IAAI,CACxB,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,OAAO,GAAE,IAAI,CAAC,OAAY,GACzB,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAS5B;AAED,MAAM,CAAC,OAAO,WAAW,IAAI,CAAC;IAC5B,gCAAgC;IAChC,KAAK,OAAO,GAAG;QACb,2DAA2D;QAC3D,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAC3B,CAAA;CACF;AAED;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAM7E"}

package/dist/ApiKeys.js

@@ -0,0 +1,166 @@
+/**
+ * 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';
+/** Zod schemas owned by the API-keys module. */
+export var schema;
+(function (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.
+     */
+    schema.MintInput = z.extend(z.omit(ApiKey.schema.ApiKey, { id: true }), {
+        createdBy: z
+            .optional(z.string())
+            .check(z.describe('Identity creating the key (e.g. admin email), recorded for audit.')),
+        expiresAt: z
+            .optional(z.string())
+            .check(z.describe('ISO 8601 expiry timestamp. Omit for a non-expiring key.')),
+        // TODO: make required once orgs exist.
+        orgId: z.optional(z.string()).check(z.describe('Owning organization id.')),
+    });
+    /**
+     * 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.
+     */
+    schema.Record = z.extend(ApiKey.schema.ApiKey, {
+        createdAt: z.string().check(z.describe('ISO 8601 creation timestamp.')),
+        createdBy: z.optional(z.string()).check(z.describe('Identity that created the key.')),
+        expiresAt: z.optional(z.string()).check(z.describe('ISO 8601 expiry timestamp.')),
+        tokenLast4: z.string().check(z.describe('Last 4 chars of the plaintext token.')),
+    });
+})(schema || (schema = {}));
+/**
+ * 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 async function mint(state, input) {
+    const valid = schema.MintInput.safeParse(input);
+    if (!valid.success)
+        throw new Error(`invalid API key input: ${z.prettifyError(valid.error)}`);
+    const data = valid.data;
+    const time = new Date();
+    const token = ApiKey.generateToken(data.environment);
+    const recordKey = ApiKey.keyFor(token);
+    const id = ApiKey.generateId();
+    const record = {
+        createdAt: time.toISOString(),
+        environment: data.environment,
+        id,
+        // TODO: drop fallback once a real org concept exists.
+        orgId: data.orgId ?? id,
+        scopes: data.scopes,
+        tokenLast4: token.slice(-4),
+        ...(data.createdBy === undefined ? {} : { createdBy: data.createdBy }),
+        ...(data.expiresAt === undefined ? {} : { expiresAt: data.expiresAt }),
+        ...(data.name === undefined ? {} : { name: data.name }),
+        ...(data.rateLimits === undefined ? {} : { rateLimits: data.rateLimits }),
+    };
+    // Bound the stored record by its expiry so the backend evicts it natively.
+    const ttl = data.expiresAt === undefined
+        ? undefined
+        : Math.max(1, Date.parse(data.expiresAt) - time.getTime());
+    await state.put(recordKey, JSON.stringify(record), { ttl });
+    // Index `id → recordKey` so revoke-by-id is O(1) (records are keyed by
+    // token hash, unrecoverable from the id alone). Shares the record's TTL so
+    // both entries expire together.
+    await state.put(idKeyFor(record.id), recordKey, { ttl });
+    return { record, token };
+}
+/**
+ * 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 async function resolve(state, token) {
+    return read(state, ApiKey.keyFor(token), Date.now());
+}
+/**
+ * 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 async function list(state, options = {}) {
+    const { keys } = await state.list({ prefix: ApiKey.recordPrefix });
+    const records = [];
+    for (const { name } of keys) {
+        const record = await read(state, name, Date.now());
+        if (record && (!options.orgId || record.orgId === options.orgId))
+            records.push(record);
+    }
+    // Newest first; ids are random, so sort by creation time.
+    return records.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+/**
+ * Revokes a key by id, deleting its record and index entry.
+ *
+ * @param state - The KV state store holding key records.
+ * @param id - The key id (`key_…`).
+ * @returns Whether a matching record was deleted.
+ */
+export async function revoke(state, id) {
+    const recordKey = await state.get(idKeyFor(id));
+    if (!recordKey)
+        return false;
+    await state.delete(recordKey);
+    await state.delete(idKeyFor(id));
+    return true;
+}
+/**
+ * Reads and validates a stored record by storage key. Invalid, corrupt, or
+ * expired records (`expiresAt <= now`) resolve to `null`.
+ */
+async function read(state, key, now) {
+    const raw = await state.get(key);
+    if (!raw)
+        return null;
+    const value = (() => {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    if (value === undefined)
+        return null;
+    const parsed = schema.Record.safeParse(value);
+    if (!parsed.success)
+        return null;
+    const record = parsed.data;
+    if (record.expiresAt !== undefined && Date.parse(record.expiresAt) <= now)
+        return null;
+    return record;
+}
+/** Storage-key prefix for the `id → recordKey` index. */
+const idPrefix = 'apikey_id:';
+/** Storage key under which a key's `id → recordKey` index entry is persisted. */
+function idKeyFor(id) {
+    return `${idPrefix}${id}`;
+}
+//# sourceMappingURL=ApiKeys.js.map

package/dist/ApiKeys.js.map

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