keyforge-anvil-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ilyasse-fouaide
+
+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

@@ -0,0 +1,168 @@
+# keyforge-anvil-client
+
+Offline-safe license client for keyforge-anvil-protected branch installations.
+
+`keyforge-anvil-client` is a Node/ESM module that runs *inside* a branch's local
+backend process to talk to keyforge-anvil (the licensing server, a separate
+repo). It is not a browser client — no UI, no framework dependency. Local
+Ed25519 signature verification is the fast, network-free path;
+server contact (`activate`/`refresh`/`deactivate`) is one-time or
+background. **The branch app must never block startup on a network call** —
+`getEntitlement()` never makes one.
+
+## Installation
+
+```bash
+npm install keyforge-anvil-client
+```
+
+## Quick start
+
+```js
+import { createKeyforgeClient } from 'keyforge-anvil-client';
+
+const client = await createKeyforgeClient({
+  publicKeys: { 1: process.env.KEYFORGE_PUBLIC_KEY_V1 },
+  baseUrl: 'https://licensing.example.com',
+});
+
+// Once, human-initiated (e.g. from a setup wizard). Throws on failure.
+await client.activate(licenseKey);
+
+// On every app boot. Network-free, never throws for expected bad states.
+const entitlement = await client.getEntitlement();
+if (entitlement.status !== 'valid') {
+  // degraded mode vs. hard stop is your app's call, not this module's
+}
+
+// Periodically in the background (e.g. every few hours). Never throws for
+// "offline" — silently no-ops so it's safe to call on a timer.
+setInterval(() => client.refresh(), 6 * 60 * 60 * 1000);
+
+// Decommissioning a branch. Throws on failure.
+await client.deactivate();
+```
+
+## Configuration
+
+`createKeyforgeClient(config)` takes a single config object:
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `publicKeys` | Yes | — | `{ [keyVersion]: pemString }`. keyforge-anvil's Ed25519 public key(s), keyed by `keyVersion` for rotation. Config, not hardcoded, so a server-side key rotation doesn't force a new release of this module. |
+| `baseUrl` | Yes | — | keyforge-anvil server base URL, e.g. `https://licensing.example.com`. |
+| `storage` | No | a JSON-file adapter at `<cwd>/.keyforge-client/state.json` | Any object implementing the `StorageAdapter` interface (`get`/`set`/`delete`, all `Promise`-returning). The default is a plain JSON file — no SQLite, no native-binary install friction. If your backend already manages its own database, implement `StorageAdapter` against it instead; pass an explicit instance (e.g. `import { createJsonFileAdapter } from 'keyforge-anvil-client'; createJsonFileAdapter({ filePath })`) to change the default file's location. |
+| `getNow` | No | real clock (unix seconds) | Injectable clock seam, mainly useful for tests. |
+| `fetchImpl` | No | global `fetch` | Injectable fetch seam, mainly useful for tests. |
+
+The returned client exposes exactly four functions: `activate(licenseKey)`,
+`getEntitlement()`, `refresh()`, `deactivate()` — matching the four
+lifecycle operations above.
+
+## `installationFingerprint`
+
+A random UUID generated transparently the first time `activate()` is
+called, and persisted under the `installationFingerprint` storage key (it
+is not part of any status object `getEntitlement()`/`refresh()` return).
+It identifies *this device*, not a particular activation:
+
+- It is reused unchanged on any later `activate()` call from the same
+  installation, which the server uses for idempotent reactivation.
+- It **survives `deactivate()`** deliberately — `deactivate()` clears
+  license-activation state (tokens, watermarks, the `revoked` flag) but
+  intentionally keeps the fingerprint, since decommissioning a license
+  isn't the same event as the device itself changing identity.
+
+## Status and error vocabulary
+
+### `getEntitlement()` statuses
+
+Always network-free, never throws for any of these — an unexpected storage
+error (e.g. corrupted state file) propagates instead of becoming a status.
+
+| Status | Meaning |
+|---|---|
+| `not_activated` | No stored entitlement token — `activate()` hasn't run yet, or `deactivate()` cleared it. |
+| `valid` | Signature, expiry, clock, and replay checks all pass. Returns `{ status, expiresAt, featureIds, features }` — `featureIds` is the token's array of licensed feature ids (keyforge-anvil's replacement for the old single `productId` claim); `features` is the open-ended capability map (currently `{ maxBranches }`). |
+| `expired` | Token's signature is valid but it's past `expiresAt`. |
+| `revoked` | The server reported a revocation on a past `refresh()` call — see [Revocation propagation](#revocation-propagation) below. |
+| `tampered` | Signature invalid, payload malformed, `installationId` doesn't match this installation, or the token is a replay of an already-superseded one. |
+| `unknown_key_version` | Token's `kid` isn't in the `publicKeys` this client was configured with — usually means local config is behind a server-side key rotation, not a fraudulent token. |
+| `clock_rollback` | Local clock is behind the last recorded validation time. |
+
+### `KeyforgeApiError` codes
+
+Thrown by `activate()`/`refresh()`/`deactivate()` for genuinely unexpected
+outcomes (never for `refresh()`'s expected "offline"/"rate limited" cases,
+which resolve to `{ status: 'offline' }` instead of throwing).
+
+**Client-side-detected** — these are synthetic codes this library produces
+locally; they are never returned by the keyforge-anvil server, so you won't find
+them in keyforge-anvil's own API docs:
+
+| Code | Meaning |
+|---|---|
+| `MALFORMED_RESPONSE` | A 2xx response body was missing required fields or wasn't valid JSON. |
+| `INSTALLATION_ID_MISMATCH` | A response's `installationToken`/entitlement token disagree on `installationId`. |
+| `STALE_TOKEN_REPLAY` | A response's token is not newer than the last one this installation accepted — rejects replayed/captured old responses. |
+
+**Server-reported** — `error.code` is passed through verbatim from
+keyforge-anvil's own error vocabulary (this library never invents a parallel
+vocabulary for these). A representative, non-exhaustive sample seen in this
+codebase's tests: `LICENSE_INVALID`, `LICENSE_REVOKED`, `RATE_LIMITED`,
+`INSTALLATION_TOKEN_INVALID`. keyforge-anvil's own docs are the authoritative,
+complete list.
+
+One related detail: the same underlying "token failed local verification"
+condition surfaces two different ways depending on which function hits it —
+`activate()` lets `TokenInvalidError`/`TokenExpiredError`/
+`UnknownKeyVersionError` (from local crypto verification) propagate as
+thrown errors, while `getEntitlement()` converts the identical condition
+into a status string (`tampered`/`expired`/`unknown_key_version`) instead
+of throwing. This follows from each function's own contract (`activate()`
+is a one-time action that should throw; `getEntitlement()` reports state
+and never throws for expected bad states), not an inconsistency.
+
+## Revocation propagation
+
+`getEntitlement()` runs entirely offline. Run purely offline, it cannot
+know about a revocation that happened after the last successful
+`refresh()` — the server can't tell a client something it hasn't
+contacted. This is inherited by design from the keyforge-anvil server's own
+architecture (revocation propagates only when a client reaches the
+server, bounded by the entitlement token's expiry window); it is not a
+defect in this client. Call `refresh()` periodically in the background to
+bound how stale that window can get.
+
+## Accepted limitations
+
+Documented here briefly; see `PROGRESS.md` for the full rationale behind
+each (found and evaluated during this project's per-phase security
+reviews):
+
+- **Clock+watermark co-tampering** — an attacker with local filesystem
+  write access (the project's existing trust boundary) can roll the clock
+  back and edit the local rollback watermark together, defeating both
+  checks for an otherwise-genuine token.
+- **Unbounded response body size** — no cap on `entitlementToken`/
+  `installationToken` string sizes accepted from a response before
+  verification.
+- **Multi-write non-atomicity** — `activate()`/`refresh()` each issue
+  several independent storage writes; a process killed mid-sequence can
+  leave state requiring a retry (fails closed, not open).
+- **`installationFingerprint`-seeding TOCTOU** — two concurrent, first-ever
+  `activate()` calls on the same client could each generate a different
+  fingerprint, with the second write silently winning.
+
+## Development
+
+- `npm test` / `npm run test:watch` — Vitest
+- `npm run lint` / `npm run lint:fix` — ESLint
+- `npm run format` / `npm run format:check` — Prettier
+
+See `CLAUDE.md` for the full command list and `ARCHITECTURE.md`/
+`PROGRESS.md` for design decisions and phase-by-phase history.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "keyforge-anvil-client",
+  "version": "0.1.0",
+  "description": "Offline-safe license client for keyforge-anvil-protected branch installations",
+  "type": "module",
+  "license": "MIT",
+  "author": "ilyasse-fouaide <ilyasse.fouaide@gmail.com>",
+  "homepage": "https://github.com/Ilyasse-Fouaide/keyforge-anvil-client#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ilyasse-Fouaide/keyforge-anvil-client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Ilyasse-Fouaide/keyforge-anvil-client/issues"
+  },
+  "keywords": [
+    "license",
+    "licensing",
+    "entitlement",
+    "offline",
+    "ed25519",
+    "keyforge",
+    "keyforge-anvil"
+  ],
+  "main": "./src/index.js",
+  "exports": "./src/index.js",
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "examples:setup": "node examples/setup-fixtures.js",
+    "examples:teardown": "node examples/teardown-fixtures.js",
+    "examples:run-all": "node examples/run-all.js"
+  },
+  "dependencies": {
+    "jose": "^6.2.8"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.8.1",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.9.0",
+    "prettier": "^3.9.6",
+    "vitest": "^4.1.10"
+  }
+}

package/src/activate.js

@@ -0,0 +1,123 @@
+// Phase 3 — POST /activate, store tokens via the storage adapter.
+//
+// Closes three of Phase 2's carry-forward items (PROGRESS.md): writes the
+// initial lastValidatedAt watermark (without it every post-activation
+// getEntitlement() call fails closed with clock_rollback, permanently),
+// seeds highestIssuedAtSeen, and stores the installationId entitlement.js
+// now checks against. A human-initiated, one-time action — throws on any
+// failure per ARCHITECTURE.md §4, never returns a status object.
+//
+// The received entitlementToken is verified locally (same crypto/ machinery
+// getEntitlement() uses) before anything is persisted. This is the load-
+// bearing defense against a MITM or malicious server: a compromised network
+// path can return whatever JSON it likes, but it cannot forge a token that
+// verifies against our configured public keys, so nothing this function
+// stores can end up trusted-but-fraudulent.
+
+import { randomUUID } from 'node:crypto';
+
+import { loadPublicKeys } from './crypto/keys.js';
+import { verifyEntitlementToken } from './crypto/verify.js';
+import { KeyforgeApiError } from './network/errors.js';
+import { apiErrorFromResponse, parseSuccessBody, postJson } from './network/request.js';
+
+const defaultGetNow = () => Math.floor(Date.now() / 1000);
+
+/**
+ * @param {object} options
+ * @param {import('./storage/adapter.js').StorageAdapter} options.storage
+ * @param {Record<string, string>} options.publicKeys - keyVersion -> PEM string
+ * @param {string} options.baseUrl - Keyforge base URL, e.g. 'https://licensing.example.com'
+ * @param {() => number} [options.getNow]
+ * @param {typeof fetch} [options.fetchImpl]
+ * @returns {Promise<{ activate: (licenseKey: string) => Promise<{ expiresAt: number }> }>}
+ */
+export async function createActivateClient({
+  storage,
+  publicKeys,
+  baseUrl,
+  getNow = defaultGetNow,
+  fetchImpl = fetch,
+}) {
+  const publicKeysByVersion = await loadPublicKeys(publicKeys);
+
+  async function activate(licenseKey) {
+    let installationFingerprint = await storage.get('installationFingerprint');
+    if (installationFingerprint === null) {
+      installationFingerprint = randomUUID();
+      await storage.set('installationFingerprint', installationFingerprint);
+    }
+
+    const response = await postJson(
+      baseUrl,
+      '/api/v1/licenses/activate',
+      { licenseKey, installationFingerprint },
+      fetchImpl,
+    );
+
+    if (response.status !== 201) {
+      throw await apiErrorFromResponse(response);
+    }
+
+    const body = await parseSuccessBody(response);
+    const { entitlementToken, installationToken, installationId } = body?.data ?? {};
+    if (
+      typeof entitlementToken !== 'string' ||
+      typeof installationToken !== 'string' ||
+      typeof installationId !== 'string' ||
+      installationId.length === 0
+    ) {
+      throw new KeyforgeApiError(
+        response.status,
+        'MALFORMED_RESPONSE',
+        'activate() response is missing required fields',
+      );
+    }
+
+    const now = getNow();
+    // Verify before trusting anything else in the response — see module
+    // comment. Left to propagate as-is (TokenInvalidError/TokenExpiredError/
+    // UnknownKeyVersionError): a malformed/malicious/stale-key response here
+    // is a genuine failure this one-time action should throw for, not a
+    // status this module invents a mapping for.
+    const payload = await verifyEntitlementToken(entitlementToken, { publicKeysByVersion, now });
+
+    if (String(payload.installationId) !== installationId) {
+      throw new KeyforgeApiError(
+        response.status,
+        'INSTALLATION_ID_MISMATCH',
+        'activate() response installationId does not match the entitlement token payload',
+      );
+    }
+
+    // Reject a stale or replayed response BEFORE persisting anything, same
+    // defense as refresh() (see its module comment) — guards an
+    // already-active installation against a MITM/malicious server replaying
+    // an old, still-validly-signed /activate response. Only meaningful when
+    // there's a prior watermark to compare against: a genuinely fresh
+    // device, or one that just ran deactivate() (which clears this key),
+    // has nothing to compare yet — same "absence isn't fail-closed"
+    // reasoning entitlement.js already documents for this same field.
+    const storedHighestIssuedAt = await storage.get('highestIssuedAtSeen');
+    const highestIssuedAtSeen =
+      storedHighestIssuedAt === null ? null : Number(storedHighestIssuedAt);
+    if (highestIssuedAtSeen !== null && payload.issuedAt <= highestIssuedAtSeen) {
+      throw new KeyforgeApiError(
+        response.status,
+        'STALE_TOKEN_REPLAY',
+        'activate() response entitlementToken is not newer than the last one seen',
+      );
+    }
+
+    await storage.set('entitlementToken', entitlementToken);
+    await storage.set('installationToken', installationToken);
+    await storage.set('installationId', payload.installationId);
+    await storage.set('lastValidatedAt', String(now));
+    await storage.set('highestIssuedAtSeen', String(payload.issuedAt));
+    await storage.delete('revoked');
+
+    return { expiresAt: payload.expiresAt };
+  }
+
+  return { activate };
+}

package/src/clock/rollback.js

@@ -0,0 +1,40 @@
+// Phase 2 — ported from Keyforge server's tests/helpers/offlineClock.js
+// (assertNoClockRollback), unchanged. That file lives under the server
+// repo's tests/helpers/ because it has no in-repo caller there — it's a
+// tested reference implementation for the client SDK that didn't exist yet.
+// This module is that client, so the check becomes real production code.
+
+/**
+ * Deliberately extends bare Error, not TokenVerificationError: this check
+ * runs before verifyEntitlementToken is ever called, and rejects for a
+ * reason crypto/ has no visibility into (local trust state, not the
+ * token's own signature/schema/expiry).
+ */
+export class ClockRollbackDetectedError extends Error {
+  constructor(now, lastValidatedAt) {
+    super(`System clock (${now}) is behind the last recorded validation time (${lastValidatedAt})`);
+    this.name = this.constructor.name;
+    this.now = now;
+    this.lastValidatedAt = lastValidatedAt;
+  }
+}
+
+/**
+ * Requires both values to already be finite numbers and throws a plain
+ * TypeError otherwise, rather than letting `<` silently coerce (e.g.
+ * `now < undefined` is false, so a caller whose storage read for the
+ * watermark came back empty would otherwise see "no rollback detected"
+ * and fall through to trusting the cached token — exactly backwards for a
+ * check whose whole point is to fail closed on an ambiguous clock state).
+ * A TypeError, not ClockRollbackDetectedError, since this is a contract
+ * violation by the caller, not a rollback detection.
+ */
+export function assertNoClockRollback({ now, lastValidatedAt }) {
+  if (!Number.isFinite(now) || !Number.isFinite(lastValidatedAt)) {
+    throw new TypeError('assertNoClockRollback requires now and lastValidatedAt as finite numbers');
+  }
+
+  if (now < lastValidatedAt) {
+    throw new ClockRollbackDetectedError(now, lastValidatedAt);
+  }
+}

package/src/crypto/errors.js

@@ -0,0 +1,42 @@
+// Phase 2 — ported from the keyforge server's src/crypto/errors.js, unchanged
+// (keyforge-anvil's equivalent is identical).
+//
+// Deliberately does NOT extend a shared app-wide error base: this stays
+// framework-agnostic, and translating these into keyforge-anvil-client's own
+// status-object vocabulary is entitlement.js's job, not this file's.
+//
+// "Malformed" and "tampered" both collapse into TokenInvalidError rather
+// than getting their own classes — both mean "reject, don't trust this
+// token," and no caller needs to treat them differently. TokenExpiredError
+// and UnknownKeyVersionError stay distinct because a caller plausibly does
+// want to handle those differently (prompt a refresh vs. flag a stale
+// embedded key).
+
+export class TokenVerificationError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = this.constructor.name;
+  }
+}
+
+export class TokenInvalidError extends TokenVerificationError {
+  code = 'TOKEN_INVALID';
+}
+
+export class TokenExpiredError extends TokenVerificationError {
+  code = 'TOKEN_EXPIRED';
+
+  constructor(expiresAt, options) {
+    super(`Token expired at ${expiresAt}`, options);
+    this.expiresAt = expiresAt;
+  }
+}
+
+export class UnknownKeyVersionError extends TokenVerificationError {
+  code = 'UNKNOWN_KEY_VERSION';
+
+  constructor(keyVersion, options) {
+    super(`Unknown signing key version: ${keyVersion}`, options);
+    this.keyVersion = keyVersion;
+  }
+}

package/src/crypto/keys.js

@@ -0,0 +1,42 @@
+// Phase 2 — new helper, not a port. Keyforge server loads public keys from
+// a file-path manifest (its own src/crypto/keys.js); this module's own §8
+// resolution is inline PEM strings supplied at init instead (see
+// ARCHITECTURE.md §8 and PROGRESS.md's Phase 2 entry for the rationale) —
+// this file only owns the PEM-string -> CryptoKey conversion, no file I/O.
+
+import { importSPKI } from 'jose';
+
+/**
+ * Converts a `{ [keyVersion]: pemString }` config into the
+ * `Map<string, CryptoKey>` shape verifyEntitlementToken expects, keyed by
+ * version-as-string to match the JWS `kid` header (spec-string-typed).
+ * @param {Record<string, string>} publicKeys
+ * @returns {Promise<Map<string, CryptoKey>>}
+ */
+export async function loadPublicKeys(publicKeys) {
+  if (publicKeys === null || typeof publicKeys !== 'object' || Array.isArray(publicKeys)) {
+    throw new TypeError('publicKeys must be an object mapping keyVersion to a PEM string');
+  }
+
+  const entries = Object.entries(publicKeys);
+  if (entries.length === 0) {
+    throw new TypeError('publicKeys must contain at least one key');
+  }
+
+  const resolved = await Promise.all(
+    entries.map(async ([version, pem]) => {
+      if (typeof pem !== 'string' || pem.length === 0) {
+        throw new TypeError(`publicKeys['${version}'] must be a non-empty PEM string`);
+      }
+      try {
+        return [version, await importSPKI(pem, 'EdDSA')];
+      } catch (err) {
+        throw new TypeError(`publicKeys['${version}'] is not a valid EdDSA public key PEM`, {
+          cause: err,
+        });
+      }
+    }),
+  );
+
+  return new Map(resolved);
+}

package/src/crypto/verify.js

@@ -0,0 +1,117 @@
+// Phase 2 — ported from Keyforge server's src/crypto/verify.js. Same jose
+// call (compactVerify, not jwtVerify — the payload uses this project's own
+// field names, not registered JWT claims), same error dispatch order, same
+// algorithm pin. The one substantive change: the server validates the
+// parsed payload with a zod schema (entitlementToken.schema.js); this module
+// has no zod dependency (deliberately dependency-light — see ARCHITECTURE.md
+// §3), so assertValidPayloadShape below checks only the one field this
+// module's own logic branches on (expiresAt) instead of porting the full
+// schema. Signature verification already proves authenticity; the server
+// validated shape at signing time.
+
+import { compactVerify } from 'jose';
+
+import {
+  TokenVerificationError,
+  TokenInvalidError,
+  TokenExpiredError,
+  UnknownKeyVersionError,
+} from './errors.js';
+
+/**
+ * Verifies a signed entitlement token: signature, payload shape, and expiry.
+ * Rejects tampered payloads, expired tokens, and unknown key versions with
+ * distinct error types — everything else (malformed structure, bad
+ * signature, shape violations) collapses into TokenInvalidError, since none
+ * of those need different handling downstream.
+ *
+ * Key resolution happens via jose's own GetKeyFunction callback, keyed on
+ * the header's `kid`: an error thrown inside that callback
+ * (UnknownKeyVersionError below) propagates through compactVerify()
+ * unmodified, with nothing verified yet at the time it runs. That's why the
+ * outer catch checks `instanceof TokenVerificationError` first — without
+ * that check, a naive wrap would misreport an unknown key version as a
+ * generic invalid-token failure.
+ */
+export async function verifyEntitlementToken(
+  jws,
+  { publicKeysByVersion, now = Math.floor(Date.now() / 1000) },
+) {
+  const resolveKey = (protectedHeader) => {
+    const { kid } = protectedHeader;
+    if (typeof kid !== 'string' || kid.length === 0) {
+      throw new TokenInvalidError('Token header is missing kid');
+    }
+
+    const key = publicKeysByVersion.get(kid);
+    if (!key) {
+      throw new UnknownKeyVersionError(kid);
+    }
+
+    return key;
+  };
+
+  let payloadBytes;
+  let protectedHeader;
+  try {
+    // Pinning algorithms prevents algorithm-confusion attacks (e.g. a
+    // crafted alg: 'none' or alg: 'HS256' token). For Ed25519 keys
+    // specifically, jose already independently refuses both of those cases
+    // via its own type checking, so this pin is currently redundant with
+    // that — kept anyway as explicit, load-bearing-by-design defense in
+    // depth rather than an incidental side effect of jose's internals, and
+    // because it stops being redundant the moment this module ever has to
+    // deal with more than one key type.
+    ({ payload: payloadBytes, protectedHeader } = await compactVerify(jws, resolveKey, {
+      algorithms: ['EdDSA'],
+    }));
+  } catch (err) {
+    if (err instanceof TokenVerificationError) throw err;
+    throw new TokenInvalidError('Token signature verification failed', { cause: err });
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(new TextDecoder().decode(payloadBytes));
+    assertValidPayloadShape(payload);
+  } catch (err) {
+    throw new TokenInvalidError('Token payload invalid', { cause: err });
+  }
+
+  // Header and payload are both covered by the signature, so these can't
+  // actually diverge post-verification given the server is the only writer
+  // — cheap to assert anyway as a backstop against a future writer that
+  // isn't.
+  if (String(payload.keyVersion) !== protectedHeader.kid) {
+    throw new TokenInvalidError('Token keyVersion does not match header kid');
+  }
+
+  if (now > payload.expiresAt) {
+    throw new TokenExpiredError(payload.expiresAt);
+  }
+
+  return payload;
+}
+
+/**
+ * Minimal shape guard, scoped to only what this module consumes.
+ * `expiresAt` must be checked explicitly: `now > payload.expiresAt` is
+ * `false` when `expiresAt` is `undefined` (or any other non-number), which
+ * would otherwise make a malformed token silently read as "never expires"
+ * instead of being rejected — the same silent-permissive-fallthrough shape
+ * as the clock-rollback bug this module's clock/ guards against.
+ * `keyVersion` needs no separate check — the cross-check above already
+ * rejects a missing/undefined value, since `String(undefined)` can't match
+ * a real `kid`. `featureIds` (keyforge-anvil's replacement for the old
+ * single `productId` claim) and `features` are both passed through opaquely
+ * and unvalidated: neither is compared or branched on here, only relayed to
+ * the caller (`entitlement.js` surfaces both on a `valid` status).
+ */
+function assertValidPayloadShape(payload) {
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new TypeError('Entitlement token payload must be a JSON object');
+  }
+  if (!Number.isFinite(payload.expiresAt)) {
+    throw new TypeError('Entitlement token payload is missing a valid expiresAt');
+  }
+}

package/src/deactivate.js

@@ -0,0 +1,47 @@
+// Phase 3 — POST /deactivate for branch decommissioning.
+//
+// A deliberate, human-initiated action — throws on any failure (including
+// network unreachability, unlike refresh()) per ARCHITECTURE.md §4. On
+// success, clears all locally stored license-activation state so a
+// subsequent getEntitlement() call reports the existing 'not_activated'
+// status — no new vocabulary needed. installationFingerprint is
+// deliberately kept: it identifies this device, not this activation, and
+// survives across a future re-activation.
+
+import { apiErrorFromResponse, postJson } from './network/request.js';
+
+/**
+ * @param {object} options
+ * @param {import('./storage/adapter.js').StorageAdapter} options.storage
+ * @param {string} options.baseUrl
+ * @param {typeof fetch} [options.fetchImpl]
+ * @returns {Promise<{ deactivate: () => Promise<void> }>}
+ */
+export async function createDeactivateClient({ storage, baseUrl, fetchImpl = fetch }) {
+  async function deactivate() {
+    const installationToken = await storage.get('installationToken');
+    if (installationToken === null) {
+      return; // nothing to deactivate
+    }
+
+    const response = await postJson(
+      baseUrl,
+      '/api/v1/licenses/deactivate',
+      { installationToken },
+      fetchImpl,
+    );
+
+    if (response.status !== 204) {
+      throw await apiErrorFromResponse(response);
+    }
+
+    await storage.delete('entitlementToken');
+    await storage.delete('installationToken');
+    await storage.delete('installationId');
+    await storage.delete('lastValidatedAt');
+    await storage.delete('highestIssuedAtSeen');
+    await storage.delete('revoked');
+  }
+
+  return { deactivate };
+}

package/src/entitlement.js

@@ -0,0 +1,137 @@
+// Phase 2 — getEntitlement(): local verification composition.
+//
+// Composes clock-rollback detection with signature verification, in that
+// order — ported from Keyforge server's tests/offline-flow/clientVerification.test.js
+// verifyStoredToken helper: the clock check is a bare, unguarded statement
+// that runs to completion (or throws) before verifyEntitlementToken is ever
+// called. Translated here from that file's exception-based contract into
+// this module's own status-object vocabulary (ARCHITECTURE.md §4/§9).
+
+import { assertNoClockRollback, ClockRollbackDetectedError } from './clock/rollback.js';
+import { TokenExpiredError, TokenInvalidError, UnknownKeyVersionError } from './crypto/errors.js';
+import { loadPublicKeys } from './crypto/keys.js';
+import { verifyEntitlementToken } from './crypto/verify.js';
+
+const defaultGetNow = () => Math.floor(Date.now() / 1000);
+
+/**
+ * @param {object} options
+ * @param {import('./storage/adapter.js').StorageAdapter} options.storage
+ * @param {Record<string, string>} options.publicKeys - keyVersion -> PEM string
+ * @param {() => number} [options.getNow] - injectable clock seam for tests; defaults to real time (unix seconds)
+ * @returns {Promise<{ getEntitlement: () => Promise<object> }>}
+ */
+export async function createEntitlementChecker({ storage, publicKeys, getNow = defaultGetNow }) {
+  const publicKeysByVersion = await loadPublicKeys(publicKeys);
+
+  async function getEntitlement() {
+    const tokenStr = await storage.get('entitlementToken');
+    if (tokenStr === null) {
+      return { status: 'not_activated' };
+    }
+
+    // A server-reported revocation (set by refresh() on a 403 entitlement-
+    // failure response — Phase 3) short-circuits everything else: a still-
+    // validly-signed, still-unexpired token tells us nothing about
+    // revocation that happened after the last successful refresh()
+    // (ARCHITECTURE.md §7), so once refresh() has told us, that verdict
+    // wins over anything the cached token itself would otherwise report. No
+    // clock check, no watermark writes on this path — there's nothing left
+    // to protect once the installation itself is revoked.
+    const revoked = await storage.get('revoked');
+    if (revoked === 'true') {
+      return { status: 'revoked' };
+    }
+
+    const now = getNow();
+    const storedLastValidatedAt = await storage.get('lastValidatedAt');
+    // storage.get() resolves null for a missing key — pass that through as
+    // null, NOT Number(null) (which is 0, a finite number). Coercing it
+    // would silently defeat assertNoClockRollback's fail-closed guard for
+    // "entitlementToken exists but no watermark has ever been written yet"
+    // (the state before Phase 3's activate() has run).
+    const lastValidatedAt = storedLastValidatedAt === null ? null : Number(storedLastValidatedAt);
+
+    try {
+      assertNoClockRollback({ now, lastValidatedAt });
+    } catch (err) {
+      if (err instanceof TypeError || err instanceof ClockRollbackDetectedError) {
+        return { status: 'clock_rollback' };
+      }
+      throw err; // unexpected — propagate, never swallow into a fake status
+    }
+
+    // Ratchet the watermark forward now that the clock check has passed,
+    // regardless of what verification below decides — the observation "now
+    // is at least this far along" is true independent of this particular
+    // token's own validity. This closes the gap where a NAIVE clock
+    // rollback (rolling the clock back without also editing this stored
+    // value) would let an already-observed-expired token look valid again.
+    // It is NOT protection against an attacker who edits this file directly
+    // alongside the clock — that requires the same local filesystem write
+    // access the token file itself already assumes as the trust boundary
+    // (ARCHITECTURE.md §5); no purely local, secret-free value can defend
+    // against a party who can edit it directly. Accepted, documented
+    // limitation — see PROGRESS.md's Phase 2 entry, same shape as §7's
+    // revocation-propagation trade-off. Never reached on the rollback path
+    // above, so a detected (or ambiguous) rollback never regresses the
+    // stored watermark.
+    await storage.set('lastValidatedAt', String(now));
+
+    try {
+      const payload = await verifyEntitlementToken(tokenStr, { publicKeysByVersion, now });
+
+      // Reject a validly-signed token that belongs to a DIFFERENT
+      // installation: signature/expiry alone can't distinguish "issued to
+      // this device" from "issued to some other device, and copied here."
+      // installationId is written by activate() (Phase 3) from the same
+      // signed payload this check reads, so a mismatch here means either
+      // the stored value or the token was swapped independently of the
+      // other — collapsed into 'tampered' rather than a new status, same
+      // category as a signature-tampered token (ARCHITECTURE.md §9: don't
+      // invent a parallel vocabulary).
+      const storedInstallationId = await storage.get('installationId');
+      if (
+        storedInstallationId !== null &&
+        String(payload.installationId) !== storedInstallationId
+      ) {
+        return { status: 'tampered' };
+      }
+
+      // Reject replay of a superseded (but still validly-signed, still
+      // unexpired) token: without this, restoring an old entitlementToken
+      // file — e.g. one saved before a downgrade — verifies cleanly and
+      // reports valid, since signature/expiry alone can't distinguish "the
+      // current token" from "a still-unexpired token this installation
+      // already moved past." Mirrors lastValidatedAt's watermark pattern,
+      // but keyed on the signature-authenticated payload.issuedAt rather
+      // than local clock time. Unlike lastValidatedAt, a missing watermark
+      // here is NOT fail-closed: the first token an installation ever
+      // verifies has nothing prior to compare against, so absence just
+      // means "nothing seen yet," not "something is wrong."
+      const storedHighestIssuedAt = await storage.get('highestIssuedAtSeen');
+      const highestIssuedAtSeen =
+        storedHighestIssuedAt === null ? null : Number(storedHighestIssuedAt);
+      if (highestIssuedAtSeen !== null && payload.issuedAt < highestIssuedAtSeen) {
+        return { status: 'tampered' };
+      }
+      if (highestIssuedAtSeen === null || payload.issuedAt > highestIssuedAtSeen) {
+        await storage.set('highestIssuedAtSeen', String(payload.issuedAt));
+      }
+
+      return {
+        status: 'valid',
+        expiresAt: payload.expiresAt,
+        featureIds: payload.featureIds,
+        features: payload.features,
+      };
+    } catch (err) {
+      if (err instanceof TokenExpiredError) return { status: 'expired' };
+      if (err instanceof UnknownKeyVersionError) return { status: 'unknown_key_version' };
+      if (err instanceof TokenInvalidError) return { status: 'tampered' };
+      throw err; // unexpected — propagate, never swallow into a fake status
+    }
+  }
+
+  return { getEntitlement };
+}

package/src/index.js

@@ -0,0 +1,58 @@
+// Phase 4 — public API surface.
+//
+// Composes the four independent lifecycle factories (Phases 2-3) into one
+// client, constructed once from a single shared config object, exposing
+// exactly ARCHITECTURE.md §4's literal call shapes: activate(licenseKey),
+// getEntitlement(), refresh(), deactivate(). Each sub-factory destructures
+// only the config keys it needs, so the same object is safe to pass to all
+// four (e.g. createDeactivateClient simply ignores publicKeys/getNow).
+//
+// storage defaults to a plain JSON-file adapter when omitted, continuing
+// this project's already-settled "default storage is a plain JSON file"
+// decision (ARCHITECTURE.md §5, CLAUDE.md) up to this composed-client level.
+
+import { createActivateClient } from './activate.js';
+import { createDeactivateClient } from './deactivate.js';
+import { createEntitlementChecker } from './entitlement.js';
+import { createRefreshClient } from './refresh.js';
+import { createJsonFileAdapter } from './storage/json-file.js';
+
+/**
+ * @param {object} options
+ * @param {import('./storage/adapter.js').StorageAdapter} [options.storage] - defaults to a JSON-file adapter at the default path
+ * @param {Record<string, string>} options.publicKeys - keyVersion -> PEM string
+ * @param {string} options.baseUrl - Keyforge base URL, e.g. 'https://licensing.example.com'
+ * @param {() => number} [options.getNow]
+ * @param {typeof fetch} [options.fetchImpl]
+ * @returns {Promise<{
+ *   activate: (licenseKey: string) => Promise<{ expiresAt: number }>,
+ *   getEntitlement: () => Promise<object>,
+ *   refresh: () => Promise<object>,
+ *   deactivate: () => Promise<void>,
+ * }>}
+ */
+export { createJsonFileAdapter };
+
+export async function createKeyforgeClient({
+  storage = createJsonFileAdapter(),
+  publicKeys,
+  baseUrl,
+  getNow,
+  fetchImpl,
+}) {
+  const sharedConfig = { storage, publicKeys, baseUrl, getNow, fetchImpl };
+
+  const [activateClient, entitlementChecker, refreshClient, deactivateClient] = await Promise.all([
+    createActivateClient(sharedConfig),
+    createEntitlementChecker(sharedConfig),
+    createRefreshClient(sharedConfig),
+    createDeactivateClient(sharedConfig),
+  ]);
+
+  return {
+    activate: activateClient.activate,
+    getEntitlement: entitlementChecker.getEntitlement,
+    refresh: refreshClient.refresh,
+    deactivate: deactivateClient.deactivate,
+  };
+}

package/src/network/errors.js

@@ -0,0 +1,23 @@
+// Phase 3 — the one new error type for the network surface: a structured,
+// non-2xx (and otherwise unhandled) response from the Keyforge API. Kept
+// separate from src/crypto/errors.js's TokenVerificationError hierarchy —
+// that hierarchy is about a token failing *local* verification; this one is
+// about the *server* rejecting a request outright. Different failure domain,
+// different vocabulary (mirrors ARCHITECTURE.md §9's "don't invent a
+// parallel vocabulary" guidance by reusing the server's own `code` values
+// verbatim rather than re-deriving new ones).
+
+export class KeyforgeApiError extends Error {
+  /**
+   * @param {number} status - HTTP status code, or 0 if there was no response at all
+   * @param {string} code - server's `error.code`, or a synthetic one (e.g. `MALFORMED_RESPONSE`)
+   * @param {string} [message]
+   * @param {ErrorOptions} [options]
+   */
+  constructor(status, code, message, options) {
+    super(message ?? `Keyforge API request failed (${code})`, options);
+    this.name = this.constructor.name;
+    this.status = status;
+    this.code = code;
+  }
+}

package/src/network/request.js

@@ -0,0 +1,61 @@
+// Phase 3 — small shared plumbing for the three network operations
+// (activate/refresh/deactivate): identical POST-JSON request shape and
+// identical `{ error: { code, message } }` envelope parsing, per
+// docs/client-sdk-integration.md's error format. No HTTP client dependency:
+// `fetchImpl` defaults to the global `fetch` (Node engine is already >=24).
+
+import { KeyforgeApiError } from './errors.js';
+
+/**
+ * @param {string} baseUrl
+ * @param {string} path
+ * @param {object} payload
+ * @param {typeof fetch} fetchImpl
+ */
+export function postJson(baseUrl, path, payload, fetchImpl) {
+  return fetchImpl(`${baseUrl}${path}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+}
+
+/**
+ * Parses a success (2xx) response body, converting a missing/malformed JSON
+ * body into a KeyforgeApiError rather than letting a raw SyntaxError escape
+ * — a malicious/broken server sending e.g. `201` with an empty or non-JSON
+ * body should fail the same recognizable way as any other bad response.
+ * @param {Response} response
+ */
+export async function parseSuccessBody(response) {
+  try {
+    return await response.json();
+  } catch (err) {
+    throw new KeyforgeApiError(
+      response.status,
+      'MALFORMED_RESPONSE',
+      'Response body is not valid JSON',
+      {
+        cause: err,
+      },
+    );
+  }
+}
+
+/**
+ * Builds a KeyforgeApiError from a non-success Response, tolerating a
+ * missing/malformed error body rather than throwing while handling an
+ * already-exceptional path.
+ * @param {Response} response
+ */
+export async function apiErrorFromResponse(response) {
+  let body = null;
+  try {
+    body = await response.json();
+  } catch {
+    // no/invalid JSON body — fall through to the synthetic code below
+  }
+  const code = body?.error?.code ?? 'MALFORMED_RESPONSE';
+  const message = body?.error?.message;
+  return new KeyforgeApiError(response.status, code, message);
+}

package/src/refresh.js

@@ -0,0 +1,125 @@
+// Phase 3 — POST /refresh, connectivity-gated, silent no-op offline.
+//
+// Closes Phase 2's other carry-forward item: gives refresh() a way to record
+// a server-reported revocation so getEntitlement() can ever report
+// 'revoked' (PROGRESS.md). Unlike activate()/deactivate(), this must never
+// throw for "offline" or "try again later" (unreachable network, 429
+// RATE_LIMITED) — those are expected, routine outcomes for a background
+// operation. It DOES throw for genuinely unexpected server responses (e.g.
+// 401 INSTALLATION_TOKEN_INVALID, 5xx, malformed body).
+//
+// The received entitlementToken is verified locally before being persisted,
+// same MITM defense as activate() — a response arrives over the same
+// network path and deserves the same signature gate before being trusted.
+
+import { loadPublicKeys } from './crypto/keys.js';
+import { verifyEntitlementToken } from './crypto/verify.js';
+import { KeyforgeApiError } from './network/errors.js';
+import { apiErrorFromResponse, parseSuccessBody, postJson } from './network/request.js';
+
+const defaultGetNow = () => Math.floor(Date.now() / 1000);
+
+/**
+ * @param {object} options
+ * @param {import('./storage/adapter.js').StorageAdapter} options.storage
+ * @param {Record<string, string>} options.publicKeys - keyVersion -> PEM string
+ * @param {string} options.baseUrl
+ * @param {() => number} [options.getNow]
+ * @param {typeof fetch} [options.fetchImpl]
+ * @returns {Promise<{ refresh: () => Promise<object> }>}
+ */
+export async function createRefreshClient({
+  storage,
+  publicKeys,
+  baseUrl,
+  getNow = defaultGetNow,
+  fetchImpl = fetch,
+}) {
+  const publicKeysByVersion = await loadPublicKeys(publicKeys);
+
+  async function refresh() {
+    const installationToken = await storage.get('installationToken');
+    if (installationToken === null) {
+      return { status: 'not_activated' };
+    }
+
+    let response;
+    try {
+      response = await postJson(
+        baseUrl,
+        '/api/v1/licenses/refresh',
+        { installationToken },
+        fetchImpl,
+      );
+    } catch {
+      // Real connectivity check: attempt-and-catch, never a
+      // navigator.onLine-style flag. Silent no-op, no state change.
+      return { status: 'offline' };
+    }
+
+    if (response.status === 429) {
+      // Same "try again later" bucket as unreachable — never throw for it.
+      return { status: 'offline' };
+    }
+
+    if (response.status === 403) {
+      await storage.set('revoked', 'true');
+      return { status: 'revoked' };
+    }
+
+    if (response.status !== 200) {
+      // Genuinely unexpected (401 INSTALLATION_TOKEN_INVALID, 400, 5xx, ...).
+      throw await apiErrorFromResponse(response);
+    }
+
+    const body = await parseSuccessBody(response);
+    const { entitlementToken } = body?.data ?? {};
+    if (typeof entitlementToken !== 'string') {
+      throw new KeyforgeApiError(
+        response.status,
+        'MALFORMED_RESPONSE',
+        'refresh() response is missing entitlementToken',
+      );
+    }
+
+    const now = getNow();
+    const payload = await verifyEntitlementToken(entitlementToken, { publicKeysByVersion, now });
+
+    const storedInstallationId = await storage.get('installationId');
+    if (storedInstallationId !== null && String(payload.installationId) !== storedInstallationId) {
+      throw new KeyforgeApiError(
+        response.status,
+        'INSTALLATION_ID_MISMATCH',
+        'refresh() response entitlementToken belongs to a different installation',
+      );
+    }
+
+    // Reject a stale or replayed response BEFORE persisting anything: a
+    // MITM (or malicious server) that captured a previously-accepted
+    // /refresh response must not be able to replay it later to roll
+    // entitlementToken back to an already-superseded token or — the
+    // critical case — to clear a `revoked` flag set by a real 403 that
+    // arrived after the captured response. Strictly-greater-than (not >=)
+    // rejects exact replays too: an honest refresh() always returns a token
+    // with a newer issuedAt than the last one this installation accepted.
+    const storedHighestIssuedAt = await storage.get('highestIssuedAtSeen');
+    const highestIssuedAtSeen =
+      storedHighestIssuedAt === null ? null : Number(storedHighestIssuedAt);
+    if (highestIssuedAtSeen !== null && payload.issuedAt <= highestIssuedAtSeen) {
+      throw new KeyforgeApiError(
+        response.status,
+        'STALE_TOKEN_REPLAY',
+        'refresh() response entitlementToken is not newer than the last one seen',
+      );
+    }
+
+    await storage.set('entitlementToken', entitlementToken);
+    await storage.set('lastValidatedAt', String(now));
+    await storage.set('highestIssuedAtSeen', String(payload.issuedAt));
+    await storage.delete('revoked');
+
+    return { status: 'updated', expiresAt: payload.expiresAt };
+  }
+
+  return { refresh };
+}

package/src/storage/adapter.js

@@ -0,0 +1,33 @@
+// Phase 1 — storage interface: get(key)/set(key,value)/delete(key).
+
+/**
+ * @typedef {object} StorageAdapter
+ * @property {(key: string) => Promise<string | null>} get
+ *   Resolves to the stored value, or `null` if `key` was never set. Never throws for a missing key.
+ * @property {(key: string, value: string) => Promise<void>} set
+ *   Stores `value` under `key`, overwriting any existing value.
+ * @property {(key: string) => Promise<void>} delete
+ *   Removes `key`. A no-op (does not throw) if `key` was never set.
+ */
+
+/**
+ * Throws a TypeError unless `key` is a non-empty string. Shared by every
+ * StorageAdapter implementation so the key contract can't drift between them.
+ * @param {unknown} key
+ */
+export function assertValidKey(key) {
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new TypeError(`StorageAdapter key must be a non-empty string, got: ${String(key)}`);
+  }
+}
+
+/**
+ * Throws a TypeError unless `value` is a string. Shared by every
+ * StorageAdapter implementation so the value contract can't drift between them.
+ * @param {unknown} value
+ */
+export function assertValidValue(value) {
+  if (typeof value !== 'string') {
+    throw new TypeError(`StorageAdapter value must be a string, got: ${typeof value}`);
+  }
+}

package/src/storage/json-file.js

@@ -0,0 +1,78 @@
+// Phase 1 — default adapter, plain JSON file via node:fs.
+
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { assertValidKey, assertValidValue } from './adapter.js';
+
+/**
+ * Default StorageAdapter (ARCHITECTURE.md §5): a single flat JSON file on
+ * disk, `{ [key]: value }`. Not one-file-per-key — the interface never asks
+ * for listing/iterating keys, so one file is simpler and sufficient.
+ *
+ * @param {object} [options]
+ * @param {string} [options.filePath] Defaults to `.keyforge-client/state.json`
+ *   under the current working directory, mirroring Keyforge's own
+ *   cwd-relative convention for local file state (see
+ *   `scripts/generate-signing-keypair.js`'s `keys/` directory).
+ * @returns {import('./adapter.js').StorageAdapter}
+ */
+export function createJsonFileAdapter({ filePath } = {}) {
+  const resolvedPath = filePath ?? path.join(process.cwd(), '.keyforge-client', 'state.json');
+  const tmpPath = `${resolvedPath}.tmp`;
+
+  // Serializes every get/set/delete on this adapter instance so concurrent
+  // calls can't interleave a read-modify-write and lose an update.
+  let queue = Promise.resolve();
+  function enqueue(operation) {
+    const result = queue.then(operation);
+    // Keep the chain alive even if this operation rejects, so later queued
+    // operations still run instead of hanging behind a rejected promise.
+    queue = result.catch(() => {});
+    return result;
+  }
+
+  async function readStore() {
+    try {
+      return JSON.parse(await readFile(resolvedPath, 'utf8'));
+    } catch (err) {
+      if (err.code === 'ENOENT') return {};
+      throw err;
+    }
+  }
+
+  async function writeStore(store) {
+    await mkdir(path.dirname(resolvedPath), { recursive: true, mode: 0o700 });
+    await writeFile(tmpPath, JSON.stringify(store, null, 2), { mode: 0o600 });
+    await rename(tmpPath, resolvedPath);
+  }
+
+  return {
+    async get(key) {
+      assertValidKey(key);
+      return enqueue(async () => {
+        const store = await readStore();
+        return store[key] ?? null;
+      });
+    },
+
+    async set(key, value) {
+      assertValidKey(key);
+      assertValidValue(value);
+      return enqueue(async () => {
+        const store = await readStore();
+        store[key] = value;
+        await writeStore(store);
+      });
+    },
+
+    async delete(key) {
+      assertValidKey(key);
+      return enqueue(async () => {
+        const store = await readStore();
+        delete store[key];
+        await writeStore(store);
+      });
+    },
+  };
+}