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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# Ear Tag (`@fungi.computer/ear-tag`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ear Tag is an independent, modular key server for TypeScript hosts. Its base
+entrypoint creates cryptographically random bearer keys and SHA-256 digests, so
+a host can issue a secret like an invite code or an API key without inventing
+its own random-string and hashing logic. `./grants` builds a typed
+capability-grant vocabulary, and `./keys` runs a tenant-scoped key store on top
+of it: issuance, verification, compare-and-swap grant edits, revocation,
+optional expiry, owner suspension and a per-key rate limit. The owner decides
+scope, storage and policy; Ear Tag owns the mechanics.
+
+## Install or set up
+
+```sh
+npm install @fungi.computer/ear-tag
+```
+
+The package ships ESM only and depends on [Cairn](../cairn/README.md) for
+identifiers and random strings, and on `zod` for its schemas. Hashing uses the
+global Web Crypto API (`crypto.subtle.digest`), available in Node 19+ and in
+Workers runtimes. It has four entrypoints: `@fungi.computer/ear-tag` (the crypto
+primitives), `@fungi.computer/ear-tag/grants` (the grant vocabulary),
+`@fungi.computer/ear-tag/keys` (the key store, free of any Node-specific type)
+and `@fungi.computer/ear-tag/keys/node` (the `node:sqlite` adapter, so a Worker
+consumer of `./keys` never needs `@types/node` to typecheck).
+
+## Quick start
+
+This helper creates a prefixed key, stores its digest, then hands the plaintext
+to the host's authorized delivery function. The host supplies both operations;
+neither the key nor the digest is logged:
+
+```ts
+import { generateKeyAndHash } from "@fungi.computer/ear-tag";
+
+export async function issueInvite(
+  storeDigest: (digest: string) => Promise<void>,
+  deliverKey: (key: string) => Promise<void>,
+): Promise<void> {
+  const { key, digest } = await generateKeyAndHash({ prefix: "invite" });
+  await storeDigest(digest);
+  await deliverKey(key);
+}
+```
+
+The existing tests verify that a generated digest matches the plaintext key in
+[`test/crypto.test.ts`](test/crypto.test.ts).
+
+## Core concepts
+
+`generateKey(options)` returns a random bearer string. An optional prefix adds
+`<prefix>_` before the random portion. `length` controls the random portion's
+length. `hashKey(key)` returns its SHA-256 digest as lowercase hexadecimal.
+`generateKeyAndHash(options)` creates both values and returns `{ key, digest }`.
+
+## Grants and the key store
+
+`./grants` declares one host's capability vocabulary and returns the schemas and
+operations closed over it:
+
+```ts
+import { defineGrants } from "@fungi.computer/ear-tag/grants";
+
+const vocabulary = defineGrants({
+  capabilities: ["files.read", "files.write"] as const,
+});
+```
+
+`./keys` runs a tenant-scoped key store over that vocabulary. `sql` is the
+`exec(statement, ...bindings) -> { toArray() }` shape Cloudflare Durable Object
+SQLite already provides; `./keys/node`'s `fromNodeSqlite` adapts a `node:sqlite`
+database for hosts that run outside a Durable Object:
+
+```ts
+import { createKeyStore } from "@fungi.computer/ear-tag/keys";
+import { fromNodeSqlite } from "@fungi.computer/ear-tag/keys/node";
+import { DatabaseSync } from "node:sqlite";
+
+const store = createKeyStore({
+  sql: fromNodeSqlite(new DatabaseSync(":memory:")),
+  commit: (body) => Promise.resolve(body()),
+  vocabulary,
+  prefix: "demo",
+  authorizeIssuer: async () => ({ kind: "unrestricted" }),
+});
+
+const issued = await store.issue("owner-1", {
+  name: "ci bot",
+  grants: [{ capability: "files.read", targets: { kind: "all" } }],
+});
+```
+
+Every operation returns a `KeyOutcome`: `{ kind: "ok", value }` or
+`{ kind: "error", error: { code, retryAfterSeconds? } }`, with `code` one of
+`invalid` (the caller's own request failed validation), `denied` (well-formed
+but refused on its merits), `conflict`, `expired`, `rate_limited` or
+`unavailable` (the store's own state could not be read back; always logged). One
+store instance is one tenant; namespacing between tenants is the host's own
+table or storage boundary.
+
+`authorizeIssuer`'s `"bounded"` only narrows which grants an actor may assign
+through `issue` or `updateGrants`. It does not narrow which keys that actor may
+`list`, `revoke` or edit: any actor it 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`. `implies` is one level deep, not
+transitive.
+
+## API reference
+
+See the generated API reference for [the crypto primitives](docs/api/index.md),
+[`./grants`](docs/api/grants.md), [`./keys`](docs/api/keys.md) and
+[`./keys/node`](docs/api/keys-node.md), or start from
+[the index](docs/api/README.md).
+
+## Examples and checks
+
+The crypto tests cover hashing, prefixed generation, and the key/digest pair.
+The grants and key-store tests cover issuance, verification, compare-and-swap
+grant edits and replay, authority-change fencing, a stale captured principal,
+revocation, optional expiry, owner suspension, the per-key rate limit, bounded
+sub-issuance and bounded grant edits, and `admitUse` on an expired or suspended
+key, run through the exact same assertions against two backends: a real
+Cloudflare Durable Object (`pnpm run test:cloudflare`, real `state.storage.sql`
+and `transactionSync`, not an adapter standing in for them) and the package's
+own `node:sqlite` adapter (`pnpm run test:node`). Run everything with:
+
+```sh
+pnpm --filter @fungi.computer/ear-tag test
+```
+
+## Limits and errors
+
+A bearer key is a secret: anyone who obtains it can present it to the system
+that accepts it. Do not log or persist plaintext keys. Retain the digest and
+give the plaintext only to its intended recipient.
+
+`hashKey` requires Web Crypto's `crypto.subtle.digest`. Key length follows
+Cairn's raw `nanoid` sizing behavior. Callers should supply a bounded
+nonnegative integer rather than untrusted sizing input.
+
+The key store's rate limit is counted in memory, not persisted; it resets if the
+host recreates the store (for example a Durable Object waking from eviction). A
+`KeyPrincipal` returned by `verify` is a plain, unsealed data object: `current`
+and `admitUse` accept one back to resume a session cheaply, but they re-read the
+live key row and its grant version on every call, so a fabricated or stale
+principal is refused rather than trusted.
+
+## Contribute and license
+
+Ear Tag is MIT licensed. See [`LICENSE`](LICENSE).

package/dist/grants.d.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+/** How a grant's capability reaches resources. */
+export type GrantTargets = Readonly<{
+    /** The capability reaches every resource, now and later. */
+    kind: "all";
+}> | Readonly<{
+    /** The capability reaches only these resources; a later resource never joins implicitly. */
+    kind: "selected";
+    /** Bounded, explicitly chosen resource identifiers this grant covers. */
+    ids: readonly string[];
+}>;
+/** One capability bound to the resources it may act on. */
+export type Grant<Capability extends string = string> = Readonly<{
+    /** Capability name drawn from the host's declared vocabulary. */
+    capability: Capability;
+    /** Resources this grant reaches. */
+    targets: GrantTargets;
+}>;
+/** The bounded authority one key carries: 1 to 64 grants. */
+export type Scope<Capability extends string = string> = Readonly<{
+    /** Every grant the key carries. */
+    grants: readonly Grant<Capability>[];
+}>;
+/** Zod schemas and grant operations closed over one host's capability vocabulary. */
+export type GrantVocabulary<Capability extends string> = Readonly<{
+    /** Validates one capability name against the declared vocabulary. */
+    capabilityNameSchema: z.ZodType<Capability>;
+    /** Validates one grant: a vocabulary capability bound to its targets. */
+    grantSchema: z.ZodType<Grant<Capability>>;
+    /** Validates a bounded, 1-to-64-grant scope. */
+    scopeSchema: z.ZodType<Scope<Capability>>;
+    /** Dedupes and sorts grants into one canonical, order-independent form. */
+    canonicalGrants: (grants: readonly Grant<Capability>[]) => readonly Grant<Capability>[];
+    /** Whether some grant admits this capability against this optional resource. */
+    grantsAllow: (grants: readonly Grant<Capability>[], capability: Capability, resourceId?: string) => boolean;
+    /** Whether some grant admits this capability for at least one resource, without naming one. */
+    grantsList: (grants: readonly Grant<Capability>[], capability: Capability) => boolean;
+    /** Whether every grant in `child` is already admitted by `parent`. */
+    isSubset: (child: readonly Grant<Capability>[], parent: readonly Grant<Capability>[]) => boolean;
+}>;
+/** A host's capability vocabulary and its optional implied-capability classes. */
+export type GrantsDefinition<Capability extends readonly [string, ...string[]]> = Readonly<{
+    /** Every capability name a grant may name; at least one. */
+    capabilities: Capability;
+    /**
+     * Extra capabilities a grant's capability also admits, for example a
+     * manage capability that also admits a narrower read capability. Every
+     * key and value must itself be a declared capability.
+     *
+     * One level deep, not transitive: if `a` implies `b` and `b` implies `c`,
+     * a grant of `a` does not reach `c` unless `a` names `c` directly too.
+     */
+    implies?: Readonly<Partial<Record<Capability[number], readonly Capability[number][]>>>;
+}>;
+/**
+ * Rejected when a host's capability vocabulary violates `defineGrants`'
+ * invariants.
+ *
+ * This error retains neither the rejected definition nor a foreign cause.
+ */
+export declare class GrantsDefinitionError extends Error {
+    /** Stable public error name. */
+    readonly name = "GrantsDefinitionError";
+    /** Creates a fresh bounded definition error. */
+    constructor();
+}
+/**
+ * Declares one host's capability vocabulary and the zod schemas and grant
+ * operations closed over it.
+ *
+ * @throws {@link GrantsDefinitionError} When the vocabulary repeats a
+ * capability, or `implies` names a capability outside it.
+ */
+export declare function defineGrants<const Capability extends readonly [string, ...string[]]>(definition: GrantsDefinition<Capability>): GrantVocabulary<Capability[number]>;

package/dist/grants.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+/**
+ * Rejected when a host's capability vocabulary violates `defineGrants`'
+ * invariants.
+ *
+ * This error retains neither the rejected definition nor a foreign cause.
+ */
+export class GrantsDefinitionError extends Error {
+    /** Stable public error name. */
+    name = "GrantsDefinitionError";
+    /** Creates a fresh bounded definition error. */
+    constructor() {
+        super("Ear Tag grants vocabulary definition is invalid");
+    }
+}
+const capabilitiesSchema = z.array(z.string().min(1).max(128)).min(1).max(256);
+function parseImplies(definition) {
+    if (!capabilitiesSchema.safeParse(definition.capabilities).success)
+        throw new GrantsDefinitionError();
+    const capabilitySet = new Set(definition.capabilities);
+    if (capabilitySet.size !== definition.capabilities.length)
+        throw new GrantsDefinitionError();
+    // Object.entries widens the declared literal keys to `string`; every key
+    // and value is checked against `capabilitySet` below, and the returned map
+    // is itself keyed by `string`, so the vocabulary's literal union is never
+    // relied on again here.
+    const declaredImplies = definition.implies;
+    const impliesEntries = declaredImplies === undefined ? [] : Object.entries(declaredImplies);
+    for (const [capability, implied] of impliesEntries) {
+        if (!capabilitySet.has(capability))
+            throw new GrantsDefinitionError();
+        for (const impliedCapability of implied ?? [])
+            if (!capabilitySet.has(impliedCapability))
+                throw new GrantsDefinitionError();
+    }
+    return new Map(impliesEntries.map(([capability, implied]) => [capability, implied ?? []]));
+}
+/**
+ * Declares one host's capability vocabulary and the zod schemas and grant
+ * operations closed over it.
+ *
+ * @throws {@link GrantsDefinitionError} When the vocabulary repeats a
+ * capability, or `implies` names a capability outside it.
+ */
+export function defineGrants(definition) {
+    const implies = parseImplies(definition);
+    const capabilityNameSchema = z.enum(definition.capabilities);
+    const grantTargetsSchema = z.discriminatedUnion("kind", [
+        z.strictObject({ kind: z.literal("all") }),
+        z.strictObject({
+            kind: z.literal("selected"),
+            ids: z.array(z.string().min(1).max(256)).max(256),
+        }),
+    ]);
+    const grantSchema = z.strictObject({
+        capability: capabilityNameSchema,
+        targets: grantTargetsSchema,
+    });
+    const scopeSchema = z.strictObject({
+        grants: z.array(grantSchema).min(1).max(64),
+    });
+    // Merges every grant sharing a capability before canonicalizing, so two
+    // scopes naming the same authority in a different order, or split across
+    // separate grants for the same capability, always produce one identical
+    // result: a reordered retry never lands a spurious replay `conflict`.
+    const canonicalGrants = (grants) => {
+        const merged = new Map();
+        for (const grant of grants) {
+            const existing = merged.get(grant.capability);
+            if (existing === undefined) {
+                merged.set(grant.capability, grant.targets.kind === "all"
+                    ? grant.targets
+                    : { kind: "selected", ids: [...grant.targets.ids] });
+                continue;
+            }
+            merged.set(grant.capability, existing.kind === "all" || grant.targets.kind === "all"
+                ? { kind: "all" }
+                : {
+                    kind: "selected",
+                    ids: [...existing.ids, ...grant.targets.ids],
+                });
+        }
+        // Plain code-unit order: stable and locale-independent, matching how
+        // `ids` below are already sorted.
+        const byCodeUnit = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+        return [...merged.entries()]
+            .map(([capability, targets]) => ({
+            capability,
+            targets: targets.kind === "all"
+                ? targets
+                : { kind: "selected", ids: [...new Set(targets.ids)].sort() },
+        }))
+            .sort((left, right) => byCodeUnit(left.capability, right.capability));
+    };
+    const grantsAllow = (grants, capability, resourceId) => grants.some((grant) => (grant.capability === capability ||
+        implies.get(grant.capability)?.includes(capability) === true) &&
+        (grant.targets.kind === "all" ||
+            (resourceId !== undefined && grant.targets.ids.includes(resourceId))));
+    const grantsList = (grants, capability) => grants.some((grant) => grant.capability === capability &&
+        (grant.targets.kind === "all" || grant.targets.ids.length > 0));
+    const isSubset = (child, parent) => child.every((grant) => grant.targets.kind === "all"
+        ? grantsAllow(parent, grant.capability)
+        : grant.targets.ids.every((id) => grantsAllow(parent, grant.capability, id)));
+    return {
+        capabilityNameSchema,
+        grantSchema,
+        scopeSchema,
+        canonicalGrants,
+        grantsAllow,
+        grantsList,
+        isSubset,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/** Options for generating a bearer key. */
+export type GenerateKeyOptions = Readonly<{
+    /** Number of random characters after the prefix. */
+    length?: number;
+    /** Public key-family marker, without the separating underscore. */
+    prefix?: string;
+}>;
+/** A newly generated bearer key and the digest safe to retain in storage. */
+export type GeneratedKey = Readonly<{
+    /** SHA-256 digest suitable for persistence instead of the bearer secret. */
+    digest: string;
+    /** Bearer secret to disclose once to its authorized recipient. */
+    key: string;
+}>;
+/** Generate a cryptographically random bearer key. */
+export declare function generateKey(options?: GenerateKeyOptions): string;
+/** Hash a bearer key with Worker-compatible Web Crypto. */
+export declare function hashKey(key: string): Promise<string>;
+/** Generate a bearer key and the digest its owner should persist. */
+export declare function generateKeyAndHash(options?: GenerateKeyOptions): Promise<GeneratedKey>;

package/dist/index.js

@@ -0,0 +1,17 @@
+import { LONG, nanoid } from "@fungi.computer/cairn";
+/** Generate a cryptographically random bearer key. */
+export function generateKey(options = {}) {
+    const key = nanoid(options.length ?? LONG);
+    return options.prefix === undefined ? key : `${options.prefix}_${key}`;
+}
+/** Hash a bearer key with Worker-compatible Web Crypto. */
+export async function hashKey(key) {
+    const bytes = new TextEncoder().encode(key);
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Generate a bearer key and the digest its owner should persist. */
+export async function generateKeyAndHash(options = {}) {
+    const key = generateKey(options);
+    return { digest: await hashKey(key), key };
+}

package/dist/keys-node.d.ts

@@ -0,0 +1,8 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { KeySql } from "./keys.js";
+/**
+ * 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.
+ */
+export declare function fromNodeSqlite(database: DatabaseSync): KeySql;

package/dist/keys-node.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+const nodeSqliteRowSchema = z.record(z.string(), z.union([z.string(), z.number(), z.null()]));
+/**
+ * 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.
+ */
+export function fromNodeSqlite(database) {
+    return {
+        exec: (statement, ...bindings) => {
+            const prepared = database.prepare(statement);
+            if (prepared.columns().length === 0) {
+                prepared.run(...bindings);
+                return { toArray: () => [] };
+            }
+            const rows = prepared
+                .all(...bindings)
+                .map((row) => nodeSqliteRowSchema.parse(row));
+            return { toArray: () => rows };
+        },
+    };
+}