keys

Import

Import

import * as api from "@fungi.computer/ear-tag/keys";

Exports

Kind	Export	Description
Ttype alias	KeyRefusalCode	Stable, closed reasons a key-store operation refuses to proceed.
Ttype alias	KeySummary	Owner-facing key metadata; neither the human owner id nor digest is exposed.
Ttype alias	KeyWire	Shared request decoders and secret-free key metadata for host transports.
Ttype alias	KeySqlValue	One bound SQL value a key store statement may carry.
Ttype alias	KeySqlRow	One materialized SQL row, keyed by column name.
Ttype alias	KeySqlCursor	Materialized result of one executed statement.
Ttype alias	KeySql	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.
Ttype alias	RateLimitPolicy	A per-key fixed-window request policy.
Ttype alias	KeyRecord	A stored key’s durable state, without its bearer secret.
Ttype alias	KeyPrincipal	A verified bearer credential: a live key’s identity and current authority.
Ttype alias	KeyRefusal	One closed refusal, carried as data rather than a thrown error type.
Ttype alias	KeyOutcome	The outcome of one key-store operation: its value, or a closed refusal.
Ttype alias	IssuerAuthority	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.
Ttype alias	AuthorityFence	One durable notice that a key’s authority changed, for a host’s own downstream fencing.
Ttype alias	AuthorityEpoch	Optional external epoch fence around a durable grant edit or revocation.
Ttype alias	CreateKeyStoreOptions	Construction options for createKeyStore.
Ttype alias	IssueKeyInput	Input to KeyStore’s issue.
Ttype alias	IssuedKey	Result of KeyStore’s issue: the bearer secret and its durable record.
Ttype alias	UpdateGrantsInput	Input to KeyStore’s updateGrants: a compare-and-swap grant replacement.
Ttype alias	RevokeInput	Input to KeyStore’s revoke: an exact, replayable revocation.
Ttype alias	AdmitUseInput	Input to KeyStore’s admitUse: one exact, replayable spend admission.
Ttype alias	KeyStore	The operations one key store exposes over its tenant’s keys.
constconstant	keyRefusalCodes	The closed refusal vocabulary used by key-owner outcomes and transport decoders.
constconstant	keyRefusalSchema	Closed key-owner refusals crossing JSON or RPC transports.
fnfunction	keyWire()	One wire grammar for both Hub and standalone Oyster key transports.
fnfunction	createKeyStore()	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.

KeyRefusalCodeTtype alias

Signature

type KeyRefusalCode = (typeof keyRefusalCodes)[number];

Stable, closed reasons a key-store operation refuses to proceed.

---

KeySummaryTtype alias

Signature

type KeySummary<Capability> = Readonly<
  Omit<KeyRecord<Capability>, "owner" | "scope"> & object
>;

Owner-facing key metadata; neither the human owner id nor digest is exposed.

Type Parameters

Type Parameter
Capability extends string

---

KeyWireTtype alias

Signature

type KeyWire<Capability> = Readonly<{
  issue: z.ZodType<IssueKeyInput<Capability>>;
  updateGrants: z.ZodType<UpdateGrantsInput<Capability>>;
  revoke: z.ZodType<RevokeInput>;
  summary: z.ZodType<KeySummary<Capability>>;
  toSummary: (record) => KeySummary<Capability>;
}>;

Shared request decoders and secret-free key metadata for host transports.

Type Parameters

Type Parameter
Capability extends string

---

KeySqlValueTtype alias

Signature

type KeySqlValue = string | number | null;

One bound SQL value a key store statement may carry.

---

KeySqlRowTtype alias

Signature

type KeySqlRow = Readonly<Record<string, KeySqlValue>>;

One materialized SQL row, keyed by column name.

---

KeySqlCursorTtype alias

Signature

type KeySqlCursor = Readonly<{
  toArray: () => readonly KeySqlRow[];
}>;

Materialized result of one executed statement.

---

KeySqlTtype alias

Signature

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.

---

RateLimitPolicyTtype alias

Signature

type RateLimitPolicy = Readonly<{
  limit: number;
  windowSeconds: number;
}>;

A per-key fixed-window request policy.

---

KeyRecordTtype alias

Signature

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

---

KeyPrincipalTtype alias

Signature

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

---

KeyRefusalTtype alias

Signature

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.

---

KeyOutcomeTtype alias

Signature

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

---

IssuerAuthorityTtype alias

Signature

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

---

AuthorityFenceTtype alias

Signature

type AuthorityFence = Readonly<{
  requestId: string;
  keyId: string;
  kind: "grants" | "revoke" | "suspend" | "close";
  throughGrantVersion: number;
  grantVersion: number;
  expiresAt: number | null;
}>;

One durable notice that a key’s authority changed, for a host’s own downstream fencing.

---

AuthorityEpochTtype alias

Signature

type AuthorityEpoch = Readonly<{
  begin: (decisionId) => Promise<void>;
  finish: (decisionId) => Promise<void>;
  abort: (decisionId) => Promise<void>;
}>;

Optional external epoch fence around a durable grant edit or revocation.

---

CreateKeyStoreOptionsTtype alias

Signature

type CreateKeyStoreOptions<Capability> = Readonly<{
  sql: KeySql;
  commit: <Value>(body) => Promise<Value>;
  vocabulary: GrantVocabulary<Capability>;
  prefix: string;
  authorizeIssuer: (actorId) => Promise<IssuerAuthority<Capability> | null>;
  delegation?: Readonly<{
    manage: Capability;
  }>;
  epoch?: AuthorityEpoch;
  onAuthorityChange?: (fence) => void;
  now?: () => number;
}>;

Construction options for createKeyStore.

Type Parameters

Type Parameter
Capability extends string

---

IssueKeyInputTtype alias

Signature

type IssueKeyInput<Capability> = Readonly<{
  name: string;
  grants: readonly Grant<Capability>[];
  keyId?: string;
  expiresAt?: number;
  rateLimit?: RateLimitPolicy;
}>;

Input to KeyStore’s issue.

Type Parameters

Type Parameter
Capability extends string

---

IssuedKeyTtype alias

Signature

type IssuedKey<Capability> = Readonly<{
  key: string;
  record: KeyRecord<Capability>;
}>;

Result of KeyStore’s issue: the bearer secret and its durable record.

Type Parameters

Type Parameter
Capability extends string

---

UpdateGrantsInputTtype alias

Signature

type UpdateGrantsInput<Capability> = Readonly<{
  requestId: string;
  keyId: string;
  expectedGrantVersion: number;
  grants: readonly Grant<Capability>[];
}>;

Input to KeyStore’s updateGrants: a compare-and-swap grant replacement.

Type Parameters

Type Parameter
Capability extends string

---

RevokeInputTtype alias

Signature

type RevokeInput = Readonly<{
  requestId: string;
  keyId: string;
}>;

Input to KeyStore’s revoke: an exact, replayable revocation.

---

AdmitUseInputTtype alias

Signature

type AdmitUseInput<Capability> = Readonly<{
  capability: Capability;
  target?: string;
  requestId: string;
}>;

Input to KeyStore’s admitUse: one exact, replayable spend admission.

Type Parameters

Type Parameter
Capability extends string

---

KeyStoreTtype alias

Signature

type KeyStore<Capability> = Readonly<{
  issue: (
    actorId,
    input,
    parent?,
  ) => Promise<KeyOutcome<IssuedKey<Capability>>>;
  verify: (secret) => Promise<KeyOutcome<KeyPrincipal<Capability>>>;
  current: (principal) => KeyOutcome<KeyPrincipal<Capability>>;
  live: (ref) => Promise<KeyOutcome<KeyPrincipal<Capability>>>;
  list: (
    actorId,
    owner?,
  ) => Promise<KeyOutcome<readonly KeyRecord<Capability>[]>>;
  updateGrants: (
    actorId,
    input,
    parent?,
  ) => Promise<KeyOutcome<KeyRecord<Capability>>>;
  revoke: (actorId, input) => Promise<KeyOutcome<KeyRecord<Capability>>>;
  suspendOwner: (owner, requestId) => Promise<KeyOutcome<void>>;
  close: (closedAt) => 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

keyRefusalCodesconstconstant

Signature

const keyRefusalCodes: readonly [
  "invalid",
  "denied",
  "conflict",
  "expired",
  "rate_limited",
  "unavailable",
];

The closed refusal vocabulary used by key-owner outcomes and transport decoders.

---

keyRefusalSchemaconstconstant

Signature

const keyRefusalSchema: z.ZodType<KeyRefusal>;

Closed key-owner refusals crossing JSON or RPC transports.

keyWire()fnfunction

Signature

function keyWire<Capability>(vocabulary): KeyWire<Capability>;

One wire grammar for both Hub and standalone Oyster key transports.

Type Parameters

Type Parameter
Capability extends string

Parameters

Parameter	Type
vocabulary	GrantVocabulary<Capability>

Returns

KeyWire<Capability>

---

createKeyStore()fnfunction

Signature

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<Capability>

Returns

KeyStore<Capability>