@fungi.computer/ear-tag 0.0.0-stage → 0.0.1

package/dist/keys.d.ts

@@ -0,0 +1,242 @@
+import type { Grant, GrantVocabulary, Scope } from "./grants.js";
+/** One bound SQL value a key store statement may carry. */
+export type KeySqlValue = string | number | null;
+/** One materialized SQL row, keyed by column name. */
+export type KeySqlRow = Readonly<Record<string, KeySqlValue>>;
+/** Materialized result of one executed statement. */
+export type KeySqlCursor = Readonly<{
+    /** Every row the statement produced. */
+    toArray: () => readonly KeySqlRow[];
+}>;
+/**
+ * Synchronous SQL execution the key store runs its statements against. This
+ * shape fits Cloudflare Durable Object SQLite (`state.storage.sql`) as is.
+ * A `node:sqlite` adapter for hosts outside a Durable Object lives at
+ * `@fungi.computer/ear-tag/keys/node`, kept out of this module so a Worker
+ * consumer of this type never needs Node's own types to typecheck.
+ */
+export type KeySql = Readonly<{
+    /** Execute one statement with positional bindings and return its rows. */
+    exec: (statement: string, ...bindings: readonly KeySqlValue[]) => KeySqlCursor;
+}>;
+/** A per-key fixed-window request policy. */
+export type RateLimitPolicy = Readonly<{
+    /** Requests admitted per window. */
+    limit: number;
+    /** Window length, in seconds. */
+    windowSeconds: number;
+}>;
+/** A stored key's durable state, without its bearer secret. */
+export type KeyRecord<Capability extends string> = Readonly<{
+    /** Opaque, canonical key identifier. */
+    keyId: string;
+    /** Opaque identifier of the accountable owner this key was issued under. */
+    owner: string;
+    /** Caller-chosen label; not secret, not unique. */
+    name: string;
+    /** The key's authority, or `null` when its stored grants could not be read back. An unreadable scope carries no authority but remains revocable. */
+    scope: Scope<Capability> | null;
+    /** Monotonic version, incremented by every accepted grant edit. */
+    grantVersion: number;
+    /** Unix milliseconds after which the key stops verifying, or `null` when the owner chose no expiry. */
+    expiresAt: number | null;
+    /** Unix milliseconds the key was revoked, or `null` while still live. */
+    revokedAt: number | null;
+    /** The key's own rate policy, or `null` when unlimited. */
+    rateLimit: RateLimitPolicy | null;
+    /** Unix milliseconds of the key's last `touch`, or `null` before one. `verify` does not stamp this on its own; a host calls `touch` when it wants usage tracking. */
+    lastUsedAt: number | null;
+    /** Unix milliseconds the key was issued. */
+    createdAt: number;
+    /** Unix milliseconds of the key's last state change. */
+    updatedAt: number;
+}>;
+/** A verified bearer credential: a live key's identity and current authority. */
+export type KeyPrincipal<Capability extends string> = Readonly<{
+    /** Opaque, canonical key identifier. */
+    keyId: string;
+    /** Opaque identifier of the accountable owner this key was issued under. */
+    owner: string;
+    /** Caller-chosen label; not secret, not unique. */
+    name: string;
+    /** The key's authority at the moment it was read. */
+    scope: Scope<Capability>;
+    /** The grant version this authority was read at; used to detect a stale credential. */
+    grantVersion: number;
+    /** Unix milliseconds after which the key stops verifying, or `null` when unbounded. */
+    expiresAt: number | null;
+}>;
+/** Stable, closed reasons a key-store operation refuses to proceed. */
+export type KeyRefusalCode = "invalid" | "denied" | "conflict" | "expired" | "rate_limited" | "unavailable";
+/**
+ * One closed refusal, carried as data rather than a thrown error type.
+ *
+ * `invalid` means the caller's own input failed the operation's schema; it
+ * is the caller's bug. `denied` means well-formed input was refused on its
+ * merits (no authority, revoked, suspended). `unavailable` means the store
+ * could not read back its own state (a corrupt row, a corrupt rate limit,
+ * or any other failure that is not one of the other closed reasons); that
+ * is the store's own fault, never the caller's, and every such failure is
+ * also logged before this outcome is returned.
+ */
+export type KeyRefusal = Readonly<{
+    /** The stable, closed refusal reason. */
+    code: KeyRefusalCode;
+    /** Seconds to wait before retrying; present only for `rate_limited`. */
+    retryAfterSeconds?: number;
+}>;
+/** The outcome of one key-store operation: its value, or a closed refusal. */
+export type KeyOutcome<Value> = Readonly<Readonly<{
+    /** The operation succeeded. */
+    kind: "ok";
+    /** The operation's result. */
+    value: Value;
+}> | Readonly<{
+    /** The operation refused to proceed. */
+    kind: "error";
+    /** The closed refusal. */
+    error: KeyRefusal;
+}>>;
+/**
+ * What an issuing actor may grant. `"unrestricted"` may grant any capability
+ * in the host's vocabulary; `"bounded"` may grant only a subset of its own
+ * live grants, checked with the vocabulary's `isSubset`.
+ */
+export type IssuerAuthority<Capability extends string> = Readonly<{
+    /** The actor may grant any capability in the host's vocabulary. */
+    kind: "unrestricted";
+}> | Readonly<{
+    /** The actor may grant only a subset of `grants`. */
+    kind: "bounded";
+    /** The actor's own live grants; every new grant must be their subset. */
+    grants: readonly Grant<Capability>[];
+}>;
+/** One durable notice that a key's authority changed, for a host's own downstream fencing. */
+export type AuthorityFence = Readonly<{
+    /** The request that caused the change; stable across a safe retry. */
+    requestId: string;
+    /** The affected key. */
+    keyId: string;
+    /** The key's grant version after the change. */
+    grantVersion: number;
+    /** The key's expiry after the change, or `null` when unbounded. */
+    expiresAt: number | null;
+}>;
+/** Construction options for {@link createKeyStore}. */
+export type CreateKeyStoreOptions<Capability extends string> = Readonly<{
+    /** Synchronous SQL execution this store's tables are kept in. */
+    sql: KeySql;
+    /** Commit a durable write with the host's own transaction and recovery coverage. */
+    commit: <Value>(body: () => Value) => Promise<Value>;
+    /** The host's capability vocabulary and grant operations. */
+    vocabulary: GrantVocabulary<Capability>;
+    /** Lowercase, underscore-separated namespace for this store's bearer keys, identifiers and tables. */
+    prefix: string;
+    /**
+     * Resolve one actor's authority to issue or edit keys, or `null` to deny
+     * the actor outright. The host owns actor identity, role checks, and
+     * re-reading a parent key's live authority.
+     *
+     * `"bounded"` only narrows which grants the actor may assign (`issue`,
+     * `updateGrants`): it does not narrow which keys they may `list`, `revoke`
+     * or edit. Any actor this resolves to a non-null authority for may manage
+     * every key in the tenant, including keys another actor issued. This
+     * matches Hub's own `authorizeManage`.
+     */
+    authorizeIssuer: (actorId: string) => Promise<IssuerAuthority<Capability> | null>;
+    /** Notified, inside the host's commit, whenever a key's authority changes. */
+    onAuthorityChange?: (fence: AuthorityFence) => void;
+    /** Clock override for tests; defaults to `Date.now`. */
+    now?: () => number;
+}>;
+/** Input to {@link KeyStore}'s `issue`. */
+export type IssueKeyInput<Capability extends string> = Readonly<{
+    /** Caller-chosen label; not secret, not unique. */
+    name: string;
+    /** The grants the new key carries; 1 to 64. */
+    grants: readonly Grant<Capability>[];
+    /**
+     * Host-chosen id for the new key; omit to let the store generate one.
+     * Once an id has been used, including by a now-revoked key, it is never
+     * reused: issuing with a reused id refuses `conflict`.
+     */
+    keyId?: string;
+    /** Unix milliseconds after which the key stops verifying; omit for no expiry. */
+    expiresAt?: number;
+    /** The key's own rate policy; omit for unlimited. */
+    rateLimit?: RateLimitPolicy;
+}>;
+/** Result of {@link KeyStore}'s `issue`: the bearer secret and its durable record. */
+export type IssuedKey<Capability extends string> = Readonly<{
+    /** Bearer secret to disclose once to its authorized recipient; never stored. */
+    key: string;
+    /** The issued key's durable record. */
+    record: KeyRecord<Capability>;
+}>;
+/** Input to {@link KeyStore}'s `updateGrants`: a compare-and-swap grant replacement. */
+export type UpdateGrantsInput<Capability extends string> = Readonly<{
+    /** The request this edit belongs to; a safe retry replays the same outcome. */
+    requestId: string;
+    /** The key being edited. */
+    keyId: string;
+    /** The grant version this edit expects to replace. */
+    expectedGrantVersion: number;
+    /** The key's replacement grants; 1 to 64. */
+    grants: readonly Grant<Capability>[];
+}>;
+/** Input to {@link KeyStore}'s `revoke`: an exact, replayable revocation. */
+export type RevokeInput = Readonly<{
+    /** The request this revocation belongs to; a safe retry replays the same outcome. */
+    requestId: string;
+    /** The key being revoked. */
+    keyId: string;
+}>;
+/** Input to {@link KeyStore}'s `admitUse`: one exact, replayable spend admission. */
+export type AdmitUseInput<Capability extends string> = Readonly<{
+    /** The capability being spent. */
+    capability: Capability;
+    /** The resource it is spent against, when the capability is resource-scoped. */
+    target?: string;
+    /** The request this admission belongs to; a safe retry replays the same outcome. */
+    requestId: string;
+}>;
+/** The operations one key store exposes over its tenant's keys. */
+export type KeyStore<Capability extends string> = Readonly<{
+    /** Issue a new key under `actorId`'s authority. */
+    issue: (actorId: string, input: IssueKeyInput<Capability>) => Promise<KeyOutcome<IssuedKey<Capability>>>;
+    /** Verify a bearer secret and return its current principal. */
+    verify: (secret: string) => Promise<KeyOutcome<KeyPrincipal<Capability>>>;
+    /** Re-read a captured principal; refuses once its grant version goes stale. */
+    current: (principal: KeyPrincipal<Capability>) => Promise<KeyOutcome<KeyPrincipal<Capability>>>;
+    /** List every key, or every key owned by `owner`, once `actorId` is authorized to manage keys. */
+    list: (actorId: string, owner?: string) => Promise<KeyOutcome<readonly KeyRecord<Capability>[]>>;
+    /**
+     * Read one key's live principal by id, once `actorId` is authorized to
+     * manage keys covering at least this key's own grants. Refuses `denied`
+     * for an unknown, revoked or suspended key and `expired` for one past
+     * its expiry, the same as `verify`.
+     */
+    read: (actorId: string, keyId: string) => Promise<KeyOutcome<KeyPrincipal<Capability>>>;
+    /** Compare-and-swap a key's grants. */
+    updateGrants: (actorId: string, input: UpdateGrantsInput<Capability>) => Promise<KeyOutcome<KeyRecord<Capability>>>;
+    /** Tombstone a key; idempotent on repeat. */
+    revoke: (actorId: string, input: RevokeInput) => Promise<KeyOutcome<KeyRecord<Capability>>>;
+    /** Permanently suspend every key owned by `owner`, for example on its departure. Commits its own write. */
+    suspendOwner: (owner: string, requestId: string) => Promise<KeyOutcome<void>>;
+    /** Revoke every still-live key as of `closedAt`. Runs inside the caller's own transaction; it does not commit. */
+    revokeAll: (closedAt: number) => Promise<KeyOutcome<void>>;
+    /** Re-verify a capability against a principal's live authority and record one idempotent use receipt. */
+    admitUse: (principal: KeyPrincipal<Capability>, input: AdmitUseInput<Capability>) => Promise<KeyOutcome<KeyPrincipal<Capability>>>;
+    /**
+     * Stamp a key's `lastUsedAt`. The only place that writes it; `verify`
+     * never stamps on its own. Refuses `denied` for an unknown key.
+     */
+    touch: (keyId: string) => Promise<KeyOutcome<void>>;
+}>;
+/**
+ * Create one tenant-scoped key store: bearer-key issuance, verification and
+ * lifecycle over one host's capability vocabulary. One store instance is one
+ * tenant; namespacing between tenants is the host's own table or storage
+ * boundary, not a column inside this store.
+ */
+export declare function createKeyStore<Capability extends string>(options: CreateKeyStoreOptions<Capability>): KeyStore<Capability>;