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

package/docs/api/grants.md

@@ -0,0 +1,191 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/ear-tag**](README.md)
+
+---
+
+[@fungi.computer/ear-tag](README.md) / grants
+
+# grants
+
+## Classes
+
+### GrantsDefinitionError
+
+Rejected when a host's capability vocabulary violates `defineGrants`'
+invariants.
+
+This error retains neither the rejected definition nor a foreign cause.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new GrantsDefinitionError(): GrantsDefinitionError;
+```
+
+Creates a fresh bounded definition error.
+
+###### Returns
+
+[`GrantsDefinitionError`](#grantsdefinitionerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### name
+
+```ts
+readonly name: "GrantsDefinitionError" = "GrantsDefinitionError";
+```
+
+Stable public error name.
+
+###### Overrides
+
+```ts
+Error.name;
+```
+
+## Type Aliases
+
+### GrantTargets
+
+```ts
+type GrantTargets =
+  | Readonly<{
+      kind: "all";
+    }>
+  | Readonly<{
+      kind: "selected";
+      ids: readonly string[];
+    }>;
+```
+
+How a grant's capability reaches resources.
+
+---
+
+### Grant
+
+```ts
+type Grant<Capability> = Readonly<{
+  capability: Capability;
+  targets: GrantTargets;
+}>;
+```
+
+One capability bound to the resources it may act on.
+
+#### Type Parameters
+
+| Type Parameter                  | Default type |
+| ------------------------------- | ------------ |
+| `Capability` _extends_ `string` | `string`     |
+
+---
+
+### Scope
+
+```ts
+type Scope<Capability> = Readonly<{
+  grants: readonly Grant<Capability>[];
+}>;
+```
+
+The bounded authority one key carries: 1 to 64 grants.
+
+#### Type Parameters
+
+| Type Parameter                  | Default type |
+| ------------------------------- | ------------ |
+| `Capability` _extends_ `string` | `string`     |
+
+---
+
+### GrantVocabulary
+
+```ts
+type GrantVocabulary<Capability> = Readonly<{
+  capabilityNameSchema: z.ZodType<Capability>;
+  grantSchema: z.ZodType<Grant<Capability>>;
+  scopeSchema: z.ZodType<Scope<Capability>>;
+  canonicalGrants: (grants) => readonly Grant<Capability>[];
+  grantsAllow: (grants, capability, resourceId?) => boolean;
+  grantsList: (grants, capability) => boolean;
+  isSubset: (child, parent) => boolean;
+}>;
+```
+
+Zod schemas and grant operations closed over one host's capability vocabulary.
+
+#### Type Parameters
+
+| Type Parameter                  |
+| ------------------------------- |
+| `Capability` _extends_ `string` |
+
+---
+
+### GrantsDefinition
+
+```ts
+type GrantsDefinition<Capability> = Readonly<{
+  capabilities: Capability;
+  implies?: Readonly<
+    Partial<Record<Capability[number], readonly Capability[number][]>>
+  >;
+}>;
+```
+
+A host's capability vocabulary and its optional implied-capability classes.
+
+#### Type Parameters
+
+| Type Parameter                                              |
+| ----------------------------------------------------------- |
+| `Capability` _extends_ readonly \[`string`, `...string[]`\] |
+
+## Functions
+
+### defineGrants()
+
+```ts
+function defineGrants<Capability>(
+  definition,
+): GrantVocabulary<Capability[number]>;
+```
+
+Declares one host's capability vocabulary and the zod schemas and grant
+operations closed over it.
+
+#### Type Parameters
+
+| Type Parameter                                         |
+| ------------------------------------------------------ |
+| `Capability` _extends_ readonly \[`string`, `string`\] |
+
+#### Parameters
+
+| Parameter    | Type                                                    |
+| ------------ | ------------------------------------------------------- |
+| `definition` | [`GrantsDefinition`](#grantsdefinition)\<`Capability`\> |
+
+#### Returns
+
+[`GrantVocabulary`](#grantvocabulary)\<`Capability`\[`number`\]\>
+
+#### Throws
+
+[GrantsDefinitionError](#grantsdefinitionerror) When the vocabulary repeats a
+capability, or `implies` names a capability outside it.

package/docs/api/index.md

@@ -0,0 +1,100 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/ear-tag**](README.md)
+
+---
+
+[@fungi.computer/ear-tag](README.md) / index
+
+# index
+
+## Type Aliases
+
+### GenerateKeyOptions
+
+```ts
+type GenerateKeyOptions = Readonly<{
+  length?: number;
+  prefix?: string;
+}>;
+```
+
+Options for generating a bearer key.
+
+---
+
+### GeneratedKey
+
+```ts
+type GeneratedKey = Readonly<{
+  digest: string;
+  key: string;
+}>;
+```
+
+A newly generated bearer key and the digest safe to retain in storage.
+
+## Functions
+
+### generateKey()
+
+```ts
+function generateKey(options?): string;
+```
+
+Generate a cryptographically random bearer key.
+
+#### Parameters
+
+| Parameter | Type                                        |
+| --------- | ------------------------------------------- |
+| `options` | [`GenerateKeyOptions`](#generatekeyoptions) |
+
+#### Returns
+
+`string`
+
+---
+
+### hashKey()
+
+```ts
+function hashKey(key): Promise<string>;
+```
+
+Hash a bearer key with Worker-compatible Web Crypto.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `key`     | `string` |
+
+#### Returns
+
+`Promise`\<`string`\>
+
+---
+
+### generateKeyAndHash()
+
+```ts
+function generateKeyAndHash(options?): Promise<
+  Readonly<{
+    digest: string;
+    key: string;
+  }>
+>;
+```
+
+Generate a bearer key and the digest its owner should persist.
+
+#### Parameters
+
+| Parameter | Type                                        |
+| --------- | ------------------------------------------- |
+| `options` | [`GenerateKeyOptions`](#generatekeyoptions) |
+
+#### Returns
+
+`Promise`\<`Readonly`\<\{ `digest`: `string`; `key`: `string`; \}\>\>

package/docs/api/keys-node.md

@@ -0,0 +1,31 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/ear-tag**](README.md)
+
+---
+
+[@fungi.computer/ear-tag](README.md) / keys-node
+
+# keys-node
+
+## Functions
+
+### fromNodeSqlite()
+
+```ts
+function fromNodeSqlite(database): KeySql;
+```
+
+Adapt a caller-owned `node:sqlite` database to the `KeySql` port
+`createKeyStore` expects, for hosts that run outside a Durable Object. The
+caller retains the database's lifetime.
+
+#### Parameters
+
+| Parameter  | Type           |
+| ---------- | -------------- |
+| `database` | `DatabaseSync` |
+
+#### Returns
+
+[`KeySql`](keys.md#keysql)

package/docs/api/keys.md

@@ -0,0 +1,406 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/ear-tag**](README.md)
+
+---
+
+[@fungi.computer/ear-tag](README.md) / keys
+
+# keys
+
+## Type Aliases
+
+### KeySqlValue
+
+```ts
+type KeySqlValue = string | number | null;
+```
+
+One bound SQL value a key store statement may carry.
+
+---
+
+### KeySqlRow
+
+```ts
+type KeySqlRow = Readonly<Record<string, KeySqlValue>>;
+```
+
+One materialized SQL row, keyed by column name.
+
+---
+
+### KeySqlCursor
+
+```ts
+type KeySqlCursor = Readonly<{
+  toArray: () => readonly KeySqlRow[];
+}>;
+```
+
+Materialized result of one executed statement.
+
+---
+
+### KeySql
+
+```ts
+type KeySql = Readonly<{
+  exec: (statement, ...bindings) => KeySqlCursor;
+}>;
+```
+
+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.
+
+---
+
+### RateLimitPolicy
+
+```ts
+type RateLimitPolicy = Readonly<{
+  limit: number;
+  windowSeconds: number;
+}>;
+```
+
+A per-key fixed-window request policy.
+
+---
+
+### KeyRecord
+
+```ts
+type KeyRecord<Capability> = Readonly<{
+  keyId: string;
+  owner: string;
+  name: string;
+  scope: Scope<Capability> | null;
+  grantVersion: number;
+  expiresAt: number | null;
+  revokedAt: number | null;
+  rateLimit: RateLimitPolicy | null;
+  lastUsedAt: number | null;
+  createdAt: number;
+  updatedAt: number;
+}>;
+```
+
+A stored key's durable state, without its bearer secret.
+
+#### Type Parameters
+
+| Type Parameter                  |
+| ------------------------------- |
+| `Capability` _extends_ `string` |
+
+---
+
+### KeyPrincipal
+
+```ts
+type KeyPrincipal<Capability> = Readonly<{
+  keyId: string;
+  owner: string;
+  name: string;
+  scope: Scope<Capability>;
+  grantVersion: number;
+  expiresAt: number | null;
+}>;
+```
+
+A verified bearer credential: a live key's identity and current authority.
+
+#### Type Parameters
+
+| Type Parameter                  |
+| ------------------------------- |
+| `Capability` _extends_ `string` |
+
+---
+
+### KeyRefusalCode
+
+```ts
+type KeyRefusalCode =
+  | "invalid"
+  | "denied"
+  | "conflict"
+  | "expired"
+  | "rate_limited"
+  | "unavailable";
+```
+
+Stable, closed reasons a key-store operation refuses to proceed.
+
+---
+
+### KeyRefusal
+
+```ts
+type KeyRefusal = Readonly<{
+  code: KeyRefusalCode;
+  retryAfterSeconds?: number;
+}>;
+```
+
+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.
+
+---
+
+### KeyOutcome
+
+```ts
+type KeyOutcome<Value> = Readonly<
+  | Readonly<{
+      kind: "ok";
+      value: Value;
+    }>
+  | Readonly<{
+      kind: "error";
+      error: KeyRefusal;
+    }>
+>;
+```
+
+The outcome of one key-store operation: its value, or a closed refusal.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Value`        |
+
+---
+
+### IssuerAuthority
+
+```ts
+type IssuerAuthority<Capability> =
+  | Readonly<{
+      kind: "unrestricted";
+    }>
+  | Readonly<{
+      kind: "bounded";
+      grants: readonly Grant<Capability>[];
+    }>;
+```
+
+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`.
+
+#### Type Parameters
+
+| Type Parameter                  |
+| ------------------------------- |
+| `Capability` _extends_ `string` |
+
+---
+
+### AuthorityFence
+
+```ts
+type AuthorityFence = Readonly<{
+  requestId: string;
+  keyId: string;
+  grantVersion: number;
+  expiresAt: number | null;
+}>;
+```
+
+One durable notice that a key's authority changed, for a host's own downstream
+fencing.
+
+---
+
+### CreateKeyStoreOptions
+
+```ts
+type CreateKeyStoreOptions<Capability> = Readonly<{
+  sql: KeySql;
+  commit: <Value>(body) => Promise<Value>;
+  vocabulary: GrantVocabulary<Capability>;
+  prefix: string;
+  authorizeIssuer: (actorId) => Promise<IssuerAuthority<Capability> | null>;
+  onAuthorityChange?: (fence) => void;
+  now?: () => number;
+}>;
+```
+
+Construction options for [createKeyStore](#createkeystore).
+
+#### Type Parameters
+
+| Type Parameter                  |
+| ------------------------------- |
+| `Capability` _extends_ `string` |
+
+---
+
+### IssueKeyInput
+
+```ts
+type IssueKeyInput<Capability> = Readonly<{
+  name: string;
+  grants: readonly Grant<Capability>[];
+  keyId?: string;
+  expiresAt?: number;
+  rateLimit?: RateLimitPolicy;
+}>;
+```
+
+Input to [KeyStore](#keystore)'s `issue`.
+
+#### Type Parameters
+
+| Type Parameter                  |
+| ------------------------------- |
+| `Capability` _extends_ `string` |
+
+---
+
+### IssuedKey
+
+```ts
+type IssuedKey<Capability> = Readonly<{
+  key: string;
+  record: KeyRecord<Capability>;
+}>;
+```
+
+Result of [KeyStore](#keystore)'s `issue`: the bearer secret and its durable
+record.
+
+#### Type Parameters
+
+| Type Parameter                  |
+| ------------------------------- |
+| `Capability` _extends_ `string` |
+
+---
+
+### UpdateGrantsInput
+
+```ts
+type UpdateGrantsInput<Capability> = Readonly<{
+  requestId: string;
+  keyId: string;
+  expectedGrantVersion: number;
+  grants: readonly Grant<Capability>[];
+}>;
+```
+
+Input to [KeyStore](#keystore)'s `updateGrants`: a compare-and-swap grant
+replacement.
+
+#### Type Parameters
+
+| Type Parameter                  |
+| ------------------------------- |
+| `Capability` _extends_ `string` |
+
+---
+
+### RevokeInput
+
+```ts
+type RevokeInput = Readonly<{
+  requestId: string;
+  keyId: string;
+}>;
+```
+
+Input to [KeyStore](#keystore)'s `revoke`: an exact, replayable revocation.
+
+---
+
+### AdmitUseInput
+
+```ts
+type AdmitUseInput<Capability> = Readonly<{
+  capability: Capability;
+  target?: string;
+  requestId: string;
+}>;
+```
+
+Input to [KeyStore](#keystore)'s `admitUse`: one exact, replayable spend
+admission.
+
+#### Type Parameters
+
+| Type Parameter                  |
+| ------------------------------- |
+| `Capability` _extends_ `string` |
+
+---
+
+### KeyStore
+
+```ts
+type KeyStore<Capability> = Readonly<{
+  issue: (actorId, input) => Promise<KeyOutcome<IssuedKey<Capability>>>;
+  verify: (secret) => Promise<KeyOutcome<KeyPrincipal<Capability>>>;
+  current: (principal) => Promise<KeyOutcome<KeyPrincipal<Capability>>>;
+  list: (
+    actorId,
+    owner?,
+  ) => Promise<KeyOutcome<readonly KeyRecord<Capability>[]>>;
+  read: (actorId, keyId) => Promise<KeyOutcome<KeyPrincipal<Capability>>>;
+  updateGrants: (actorId, input) => Promise<KeyOutcome<KeyRecord<Capability>>>;
+  revoke: (actorId, input) => Promise<KeyOutcome<KeyRecord<Capability>>>;
+  suspendOwner: (owner, requestId) => Promise<KeyOutcome<void>>;
+  revokeAll: (closedAt) => Promise<KeyOutcome<void>>;
+  admitUse: (principal, input) => Promise<KeyOutcome<KeyPrincipal<Capability>>>;
+  touch: (keyId) => Promise<KeyOutcome<void>>;
+}>;
+```
+
+The operations one key store exposes over its tenant's keys.
+
+#### Type Parameters
+
+| Type Parameter                  |
+| ------------------------------- |
+| `Capability` _extends_ `string` |
+
+## Functions
+
+### createKeyStore()
+
+```ts
+function createKeyStore<Capability>(options): KeyStore<Capability>;
+```
+
+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.
+
+#### Type Parameters
+
+| Type Parameter                  |
+| ------------------------------- |
+| `Capability` _extends_ `string` |
+
+#### Parameters
+
+| Parameter | Type                                                              |
+| --------- | ----------------------------------------------------------------- |
+| `options` | [`CreateKeyStoreOptions`](#createkeystoreoptions)\<`Capability`\> |
+
+#### Returns
+
+[`KeyStore`](#keystore)\<`Capability`\>