@aikdna/kdna-activation-server 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 KDNA Authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/NOTICE

@@ -0,0 +1,14 @@
+kdna-activation-server
+Copyright 2026 KDNA Authors
+
+This product includes software developed at
+https://github.com/aikdna/kdna-activation-server
+
+This server is a license-management reference implementation. It
+implements specs/kdna-entitlement-api.md and the self-hosting
+invariant from docs/REMOTE_MODE.md. The server has no KDNA Inc.
+URL hardcoded; license records and the signing keypair are
+deployer-controlled.
+
+See LICENSE for the full Apache 2.0 license text. See README.md
+for the self-hosting guide and the API contract.

package/README.md

@@ -0,0 +1,189 @@
+# @aikdna/kdna-activation-server
+
+**Self-hostable HTTP activation server for KDNA `licensed`-mode assets.**
+
+This server answers one question:
+
+> Is this user / device / organisation currently entitled to use this
+> asset?
+
+It implements the four endpoints in
+[`specs/kdna-entitlement-api.md`][1] and the self-hosting invariant
+from [`docs/REMOTE_MODE.md`][2]. Reference implementation of
+roadmap-2026.md Story 24.
+
+[1]: https://github.com/aikdna/kdna/blob/main/specs/kdna-entitlement-api.md
+[2]: https://github.com/aikdna/kdna/blob/main/docs/REMOTE_MODE.md
+
+---
+
+## Self-hosting is the default
+
+> The KDNA protocol MUST NOT assume a single official KDNA
+> server. Any asset creator can run their own activation server.
+> Official KDNA hosting is one deployment option, not the
+> protocol requirement.
+
+This server is the deployer's own. The protocol does not
+hardcode any KDNA Inc. URL. The admin token is deployer-
+controlled. License records are deployer-controlled. The
+server's signing keypair is generated on first start and
+stored locally.
+
+---
+
+## Quick start (self-hosting)
+
+```bash
+# 1. Install (any Node 18+ server)
+npm install -g @aikdna/kdna-activation-server
+
+# 2. Create your first license
+kdna-activation-server --create-license '{
+  "domain": "@yourname/your-asset",
+  "license_key": "KDNA-LIC-customer-1",
+  "issued_to": "customer@example.com",
+  "ttl_days": 365
+}'
+
+# 3. Start the server
+kdna-activation-server --port 3001 --admin-token "your-secret"
+
+# 4. Test
+curl http://localhost:3001/healthz
+curl -X POST http://localhost:3001/v1/entitlements/activate \
+  -H 'Content-Type: application/json' \
+  -d '{"domain":"@yourname/your-asset","license_key":"KDNA-LIC-customer-1"}'
+```
+
+That's it. No registration, no phone-home, no KDNA Inc. URL.
+
+---
+
+## HTTP API
+
+### `GET /healthz`
+
+Health check. Returns 200 with server metadata.
+
+### `GET /v1/server/identity`
+
+Returns the server's Ed25519 public key (PEM, hex, and
+fingerprint). Clients use this to verify that an entitlement
+record was really signed by this server.
+
+### `POST /v1/entitlements/activate`
+
+Activates a license. Returns a signed entitlement record
+(cryptographically verifiable against `/v1/server/identity`).
+
+Request body:
+
+```json
+{
+  "domain": "@yourname/your-asset",
+  "license_key": "KDNA-LIC-customer-1",
+  "machine_fingerprint": "<sha256>"
+}
+```
+
+Optional: `client`, `client_version`, `agent`, `account_id`,
+`device_label`.
+
+Response (200): the signed entitlement record (see
+`specs/kdna-entitlement-api.md` §5).
+
+Errors:
+- `INVALID_LICENSE_KEY` (404) — key does not match the domain
+- `LICENSE_REVOKED` (403) — license has been revoked
+- `LICENSE_EXPIRED` (403) — `expires_at` is in the past
+
+### `POST /v1/entitlements/sync`
+
+Refreshes the entitlement state (updates `last_checked_at` and
+`offline_valid_until`). Returns the signed record. Same
+errors as `/activate`.
+
+### `POST /v1/entitlements/revoke` (admin)
+
+Revokes a license. Requires an `Authorization: Bearer
+<admin-token>` header. The admin token is set at server
+startup.
+
+Request body:
+
+```json
+{
+  "license_id": "lic_abc123",
+  "domain": "@yourname/your-asset",
+  "reason": "payment_failed",
+  "revoked_by": "billing-system"
+}
+```
+
+### `GET /v1/entitlements/status?domain=...&license_key=...`
+
+Introspection. Returns the record (unsigned, for
+introspection only; consumers should use `/activate` or
+`/sync` for the signed record).
+
+---
+
+## CLI
+
+```bash
+# Create a license (one-shot)
+kdna-activation-server --create-license '{"domain":"@x/y","license_key":"KDNA-LIC-1"}'
+
+# List all licenses
+kdna-activation-server --list
+
+# Revoke
+kdna-activation-server --revoke lic_abc123 --reason "payment_failed"
+
+# Start the server
+kdna-activation-server --port 3001 --admin-token "your-secret"
+```
+
+The server keypair is auto-generated on first start and
+stored at `~/.kdna/activation-server/`. The private key is
+mode 0600.
+
+---
+
+## Security properties
+
+- **No KDNA Inc. URL is hardcoded.** The server has zero
+  outbound network calls during normal operation.
+- **The server keypair is local.** The private key never
+  leaves the deployer's machine.
+- **The admin token is deployer-controlled.** Set it at
+  startup or omit it to disable `/revoke` over HTTP.
+- **The license_key is the secret.** The server echoes it
+  back in the activation record (per spec). Clients MUST
+  NOT log or persist it beyond the local activation file.
+- **Records are signed.** Every `/activate` and `/sync`
+  response is signed with the server's Ed25519 key. Clients
+  can verify against `/v1/server/identity`.
+
+---
+
+## Local development
+
+```bash
+git clone https://github.com/aikdna/kdna-activation-server
+cd kdna-activation-server
+npm test
+```
+
+The tests spin up the server on an OS-assigned port. No
+external services are required.
+
+---
+
+## License
+
+Apache 2.0. See [LICENSE](./LICENSE).
+
+This server is a license-management reference implementation.
+Trust is the consumer's decision, not the server's claim.

package/bin/kdna-activation-server.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * kdna-activation-server — CLI entry (Story 24)
+ *
+ * Self-hostable HTTP activation server. See README.md for
+ * self-hosting instructions.
+ *
+ * Usage:
+ *   kdna-activation-server [--port 3001] [--data-dir <path>]
+ *                          [--admin-token <secret>]
+ *                          [--create-license <json>]
+ *                          [--list]
+ *                          [--revoke <license-id> --reason "..."]
+ *
+ * The server is the deployer's own. The protocol does not
+ * hardcode any KDNA Inc. URL. The admin token is deployer-
+ * controlled. License records are deployer-controlled.
+ */
+
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { startServer, stopServer } = require('../src/server');
+const { makeStore, DEFAULT_DATA_DIR } = require('../src/store');
+const pkg = require('../package.json');
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const eq = key.indexOf('=');
+      if (eq >= 0) {
+        out[key.slice(0, eq)] = key.slice(eq + 1);
+      } else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+        out[key] = argv[i + 1];
+        i++;
+      } else {
+        out[key] = true;
+      }
+    }
+  }
+  return out;
+}
+
+function help() {
+  return `kdna-activation-server v${pkg.version} — self-hostable activation server
+
+Usage:
+  kdna-activation-server [serve options]
+  kdna-activation-server --create-license '<json>' [--data-dir <path>]
+  kdna-activation-server --list [--data-dir <path>]
+  kdna-activation-server --revoke <license-id> --reason "..." [--data-dir <path>]
+
+Server options:
+  --port <n>             Port to listen on. Default 3001.
+  --host <addr>          Host to bind. Default 127.0.0.1.
+  --data-dir <path>      Where to store entitlement records +
+                         server keypair. Default
+                         ~/.kdna/activation-server.
+  --admin-token <secret> Bearer token for the /v1/entitlements/revoke
+                         endpoint. If unset, /revoke returns 401.
+                         Set this if you want to be able to revoke
+                         licenses via HTTP.
+
+One-shot commands (do not start the server):
+  --create-license '<json>'
+                        Create a new license record. The JSON
+                        must contain: domain, license_key.
+                        Optional: issued_to, ttl_days,
+                        require_machine_binding (default true),
+                        require_online_check (default true),
+                        offline_grace_days (default 7),
+                        allowed_agents (array).
+  --list                 List all license records.
+  --revoke <id>          Revoke a license by id. Requires --reason.
+  --reason "..."         Reason for revocation (audit log).
+
+Self-hosting:
+  Run this on any Node 18+ server. There is no registration
+  with KDNA Inc. The license records, the admin token, and
+  the server keypair are all deployer-controlled.
+`;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || args.h) {
+    process.stdout.write(help());
+    return;
+  }
+
+  const dataDir = args['data-dir'] || DEFAULT_DATA_DIR;
+  fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+  const store = makeStore(dataDir);
+
+  // One-shot commands
+  if (args['create-license']) {
+    let body;
+    try {
+      body = JSON.parse(args['create-license']);
+    } catch (e) {
+      process.stderr.write(`Error: --create-license value is not valid JSON: ${e.message}\n`);
+      process.exit(1);
+    }
+    if (!body.domain || !body.license_key) {
+      process.stderr.write(`Error: --create-license JSON must include domain and license_key\n`);
+      process.exit(1);
+    }
+    const rec = store.create(body);
+    process.stdout.write(`Created license:\n  ${JSON.stringify(rec, null, 2)}\n`);
+    return;
+  }
+  if (args.list) {
+    const recs = store.list();
+    process.stdout.write(`${recs.length} license record(s):\n`);
+    for (const r of recs) {
+      process.stdout.write(`  ${r.license_id}  ${r.domain}  status=${r.status}  revoked=${r.revoked}\n`);
+    }
+    return;
+  }
+  if (args.revoke) {
+    if (!args.reason) {
+      process.stderr.write(`Error: --revoke requires --reason\n`);
+      process.exit(1);
+    }
+    const updated = store.revoke(args.revoke, { reason: args.reason, revoked_by: 'cli' });
+    if (!updated) {
+      process.stderr.write(`Error: no license found with id ${args.revoke}\n`);
+      process.exit(1);
+    }
+    process.stdout.write(`Revoked:\n  ${JSON.stringify(updated, null, 2)}\n`);
+    return;
+  }
+
+  // Start the server
+  const port = args.port ? parseInt(args.port, 10) : 3001;
+  const host = args.host || '127.0.0.1';
+  if (isNaN(port)) {
+    process.stderr.write(`Error: invalid port: ${args.port}\n`);
+    process.exit(1);
+  }
+
+  const { server, port: actualPort, keys, dataDir: dd } = await startServer({
+    dataDir,
+    port,
+    host,
+    adminToken: args['admin-token'] || null,
+  });
+
+  process.stdout.write(
+    `kdna-activation-server v${pkg.version} listening on http://${host}:${actualPort}\n` +
+      `  data_dir:     ${dd}\n` +
+      `  admin_token:  ${args['admin-token'] ? '(configured)' : '(NOT set — /revoke returns 401)'}\n` +
+      `  public_key:   ${keys.publicPem.length} bytes (PEM, ed25519)\n` +
+      `\n` +
+      `Try:\n` +
+      `  curl http://${host}:${actualPort}/healthz\n` +
+      `  curl http://${host}:${actualPort}/v1/server/identity\n` +
+      `  curl -X POST http://${host}:${actualPort}/v1/entitlements/activate \\\n` +
+      `    -H 'Content-Type: application/json' \\\n` +
+      `    -d '{"domain":"@yourname/your-asset","license_key":"KDNA-LIC-..."}'\n` +
+      `\n` +
+      `Create a license:\n` +
+      `  kdna-activation-server --create-license '{"domain":"@yourname/your-asset","license_key":"KDNA-LIC-test1"}'\n`,
+  );
+
+  const shutdown = (signal) => {
+    process.stdout.write(`\nReceived ${signal}, shutting down...\n`);
+    stopServer(server).then(() => process.exit(0));
+  };
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+}
+
+main().catch((e) => {
+  process.stderr.write(`Error: ${e.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@aikdna/kdna-activation-server",
+  "version": "0.1.0",
+  "description": "KDNA activation server — self-hostable HTTP server for license activation, sync, revocation. Implements specs/kdna-entitlement-api.md and the self-hosting invariant from docs/REMOTE_MODE.md (Story 24).",
+  "type": "commonjs",
+  "main": "src/index.js",
+  "bin": {
+    "kdna-activation-server": "bin/kdna-activation-server.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/kdna-activation-server.js",
+    "test": "node --test tests/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aikdna/kdna-activation-server.git"
+  },
+  "homepage": "https://github.com/aikdna/kdna-activation-server",
+  "keywords": [
+    "kdna",
+    "kdna-activation-server",
+    "license",
+    "entitlement",
+    "self-hosted",
+    "creator-license-management"
+  ]
+}

package/src/index.js

@@ -0,0 +1,20 @@
+/**
+ * index.js — public API for @aikdna/kdna-activation-server (Story 24)
+ */
+
+'use strict';
+
+const server = require('./server');
+const store = require('./store');
+const signing = require('./signing');
+
+module.exports = {
+  startServer: server.startServer,
+  stopServer: server.stopServer,
+  makeRequestHandler: server.makeRequestHandler,
+  makeStore: store.makeStore,
+  ensureKeyPair: signing.ensureKeyPair,
+  publicKeyFingerprint: signing.publicKeyFingerprint,
+  signEntitlement: signing.signEntitlement,
+  verifyEntitlementSignature: signing.verifyEntitlementSignature,
+};

package/src/server.js

@@ -0,0 +1,266 @@
+/**
+ * server.js — activation server HTTP layer (Story 24)
+ *
+ * Implements the four endpoints from specs/kdna-entitlement-api.md:
+ *
+ *   POST /v1/entitlements/activate
+ *     Body: { domain, license_key, machine_fingerprint?, ... }
+ *     Response: activation record (status: "active")
+ *     Errors: INVALID_LICENSE_KEY, LICENSE_REVOKED, ...
+ *
+ *   POST /v1/entitlements/sync
+ *     Body: { domain, license_key, license_id? }
+ *     Response: same as activation (refreshes last_checked_at)
+ *
+ *   POST /v1/entitlements/revoke
+ *     Auth: Bearer <admin-token>
+ *     Body: { license_id, domain, reason, revoked_by? }
+ *     Response: { ok: true, license_id, status: "revoked", ... }
+ *
+ *   GET /v1/entitlements/status?domain=...&license_key=...
+ *     Response: activation record
+ *
+ * Plus:
+ *   GET /v1/server/identity
+ *     Response: { public_key_pem, public_key_fingerprint,
+ *                 public_key_hex, ... }
+ *     Lets clients verify signed entitlement records.
+ *
+ *   GET /healthz
+ *     Response: { ok: true, server, version }
+ *
+ * Layer isolation: the server returns the activation record's
+ * fields verbatim. It does NOT add content-trust claims like
+ * "official" or "trusted" — those would contradict the KDNA
+ * layer-isolation rules (SPEC §13.1).
+ */
+
+'use strict';
+
+const http = require('node:http');
+const { URL } = require('node:url');
+const crypto = require('node:crypto');
+const { makeStore } = require('./store');
+const {
+  ensureKeyPair,
+  publicKeyFingerprint,
+  publicKeyRawHex,
+  signEntitlement,
+  verifyEntitlementSignature,
+} = require('./signing');
+
+const DEFAULT_PORT = 3001;
+
+function makeRequestHandler(opts) {
+  if (!opts.store) throw new Error('store is required');
+  if (!opts.keys) throw new Error('keys is required');
+  const { store, keys, adminToken } = opts;
+
+  async function handle(req, res) {
+    const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+
+    // Health check (always 200, no auth)
+    if (req.method === 'GET' && url.pathname === '/healthz') {
+      json(res, 200, {
+        ok: true,
+        server: '@aikdna/kdna-activation-server',
+        version: require('../package.json').version,
+        data_dir: store.dataDir,
+      });
+      return;
+    }
+
+    // Server identity — the public key clients use to verify
+    // signed entitlement records. No auth (this is a public key).
+    if (req.method === 'GET' && url.pathname === '/v1/server/identity') {
+      const rawHex = publicKeyRawHex(keys.publicPem);
+      json(res, 200, {
+        server: '@aikdna/kdna-activation-server',
+        version: require('../package.json').version,
+        public_key_pem: keys.publicPem.trim(),
+        public_key_fingerprint: publicKeyFingerprint(keys.publicPem),
+        public_key_hex: rawHex,
+        algorithm: 'ed25519',
+        signature_version: '1.0',
+      });
+      return;
+    }
+
+    // Activation
+    if (req.method === 'POST' && url.pathname === '/v1/entitlements/activate') {
+      await readJson(req, res, async (body) => {
+        const { domain, license_key } = body || {};
+        if (!domain) return jsonError(res, 400, 'MISSING_DOMAIN', 'domain is required');
+        if (!license_key) return jsonError(res, 400, 'MISSING_LICENSE_KEY', 'license_key is required');
+
+        const rec = store.getByKey(license_key);
+        if (!rec || rec.domain !== domain) {
+          return jsonError(res, 404, 'INVALID_LICENSE_KEY',
+            'license_key does not match the requested domain');
+        }
+        if (rec.revoked || rec.status === 'revoked') {
+          return jsonError(res, 403, 'LICENSE_REVOKED',
+            'license has been revoked',
+            { license_id: rec.license_id, revoked_at: rec.revoked_at, revocation_reason: rec.revocation_reason });
+        }
+        if (rec.expires_at && new Date(rec.expires_at) < new Date()) {
+          return jsonError(res, 403, 'LICENSE_EXPIRED',
+            'license has expired',
+            { license_id: rec.license_id, expires_at: rec.expires_at });
+        }
+        // Activate: refresh last_checked_at + offline_valid_until
+        store.updateSync(rec.license_id);
+        const fresh = store.get(rec.license_id);
+        const signed = signEntitlement(stripForApi(fresh), keys.privatePem);
+        return json(res, 200, signed);
+      });
+      return;
+    }
+
+    // Sync
+    if (req.method === 'POST' && url.pathname === '/v1/entitlements/sync') {
+      await readJson(req, res, async (body) => {
+        const { domain, license_key, license_id } = body || {};
+        let rec = null;
+        if (license_id) rec = store.get(license_id);
+        if (!rec && license_key) rec = store.getByKey(license_key);
+        if (!rec || (domain && rec.domain !== domain)) {
+          return jsonError(res, 404, 'INVALID_LICENSE_KEY',
+            'no entitlement matches the provided identifiers');
+        }
+        if (rec.revoked || rec.status === 'revoked') {
+          return jsonError(res, 403, 'LICENSE_REVOKED',
+            'license has been revoked',
+            { license_id: rec.license_id, revoked_at: rec.revoked_at, revocation_reason: rec.revocation_reason });
+        }
+        store.updateSync(rec.license_id);
+        const fresh = store.get(rec.license_id);
+        const signed = signEntitlement(stripForApi(fresh), keys.privatePem);
+        return json(res, 200, signed);
+      });
+      return;
+    }
+
+    // Status (introspection; lightweight)
+    if (req.method === 'GET' && url.pathname === '/v1/entitlements/status') {
+      const domain = url.searchParams.get('domain');
+      const licenseKey = url.searchParams.get('license_key');
+      const licenseId = url.searchParams.get('license_id');
+      let rec = null;
+      if (licenseId) rec = store.get(licenseId);
+      if (!rec && licenseKey) rec = store.getByKey(licenseKey);
+      if (!rec || (domain && rec.domain !== domain)) {
+        return jsonError(res, 404, 'NOT_FOUND', 'no entitlement matches');
+      }
+      return json(res, 200, stripForApi(rec));
+    }
+
+    // Revoke (admin-only, bearer token)
+    if (req.method === 'POST' && url.pathname === '/v1/entitlements/revoke') {
+      const auth = req.headers.authorization || '';
+      if (!adminToken || !auth.startsWith('Bearer ') || auth.slice(7) !== adminToken) {
+        return jsonError(res, 401, 'UNAUTHORIZED',
+          'admin bearer token required');
+      }
+      await readJson(req, res, async (body) => {
+        const { license_id, domain, reason, revoked_by } = body || {};
+        if (!license_id) return jsonError(res, 400, 'MISSING_LICENSE_ID', 'license_id is required');
+        const rec = store.get(license_id);
+        if (!rec || (domain && rec.domain !== domain)) {
+          return jsonError(res, 404, 'NOT_FOUND', 'no entitlement matches');
+        }
+        const updated = store.revoke(license_id, { reason, revoked_by });
+        return json(res, 200, {
+          ok: true,
+          license_id,
+          status: 'revoked',
+          revoked: true,
+          revoked_at: updated.revoked_at,
+          reason: updated.revocation_reason,
+          revoked_by: updated.revoked_by,
+        });
+      });
+      return;
+    }
+
+    jsonError(res, 404, 'NOT_FOUND', `no handler for ${req.method} ${url.pathname}`);
+  }
+
+  return handle;
+}
+
+/**
+ * Strip internal fields from the API response. The store keeps
+ * `updated_at`, `revoked_by`, etc. for bookkeeping; these are
+ * not part of the public entitlement record shape.
+ */
+function stripForApi(rec) {
+  const out = { ...rec };
+  delete out.revoked_by;
+  return out;
+}
+
+function readJson(req, res, fn) {
+  let body = '';
+  req.on('data', (chunk) => {
+    body += chunk;
+    if (body.length > 64 * 1024) {
+      req.destroy();
+      jsonError(res, 413, 'REQUEST_TOO_LARGE', 'request body exceeds 64KB');
+    }
+  });
+  req.on('end', async () => {
+    let parsed;
+    try {
+      parsed = body.length === 0 ? {} : JSON.parse(body);
+    } catch (e) {
+      return jsonError(res, 400, 'INVALID_JSON', `not valid JSON: ${e.message}`);
+    }
+    try {
+      await fn(parsed);
+    } catch (e) {
+      jsonError(res, 500, 'INTERNAL_ERROR', e.message);
+    }
+  });
+}
+
+function json(res, status, body) {
+  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify(body, null, 2) + '\n');
+}
+
+function jsonError(res, status, code, message, extra) {
+  json(res, status, { ok: false, error: { code, message, retryable: false, ...(extra || {}) } });
+}
+
+function startServer(opts = {}) {
+  return new Promise((resolve, reject) => {
+    const dataDir = opts.dataDir || require('./store').DEFAULT_DATA_DIR;
+    const store = opts.store || makeStore(dataDir);
+    const keys = opts.keys || ensureKeyPair(dataDir);
+    const handler = makeRequestHandler({
+      store,
+      keys,
+      adminToken: opts.adminToken || null,
+    });
+    const server = http.createServer(handler);
+    server.on('error', reject);
+    server.listen(typeof opts.port === 'number' ? opts.port : DEFAULT_PORT, opts.host || '127.0.0.1', () => {
+      const addr = server.address();
+      resolve({ server, port: addr.port, host: addr.address, store, keys, dataDir });
+    });
+  });
+}
+
+function stopServer(server) {
+  return new Promise((resolve) => {
+    if (!server) return resolve();
+    server.close(() => resolve());
+  });
+}
+
+module.exports = {
+  makeRequestHandler,
+  startServer,
+  stopServer,
+};

package/src/signing.js

@@ -0,0 +1,120 @@
+/**
+ * signing.js — Ed25519 signing of entitlement records (Story 24)
+ *
+ * The activation server can sign the entitlement records it
+ * returns. This lets clients verify that a record really came
+ * from the activation server they think it came from (the
+ * signed record + the server's public key is enough; no
+ * central CA needed).
+ *
+ * The keypair is generated on first server start and stored
+ * alongside the data directory. The private key is stored with
+ * mode 0600.
+ *
+ * This is the creator's identity key for the activation server.
+ * The same identity model as kdna-cli's `kdna identity init`
+ * (Story 19) — but in a separate file because the server
+ * identity is the SERVER's, not the deployer's CLI identity.
+ *
+ * Story 19 design contract:
+ *   - Each actor generates their own key pair.
+ *   - KDNA Inc. holds NO private keys.
+ *   - No TUF, no registry, no central authority.
+ *
+ * Same rules apply here: the server generates its own key.
+ * Clients verify against the server's public key (which the
+ * server advertises at GET /v1/server/identity).
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const PRIVATE_KEY_PATH_DEFAULT = 'activation-server-ed25519.key';
+const PUBLIC_KEY_PATH_DEFAULT = 'activation-server-ed25519.pub';
+
+function keyPaths(dataDir) {
+  return {
+    priv: path.join(dataDir, PRIVATE_KEY_PATH_DEFAULT),
+    pub: path.join(dataDir, PUBLIC_KEY_PATH_DEFAULT),
+  };
+}
+
+function ensureKeyPair(dataDir) {
+  fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+  const { priv, pub } = keyPaths(dataDir);
+  if (fs.existsSync(priv) && fs.existsSync(pub)) {
+    return {
+      privatePem: fs.readFileSync(priv, 'utf8'),
+      publicPem: fs.readFileSync(pub, 'utf8'),
+    };
+  }
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519', {
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+  });
+  fs.writeFileSync(priv, privateKey, { mode: 0o600 });
+  fs.writeFileSync(pub, publicKey, { mode: 0o644 });
+  return { privatePem: privateKey, publicPem: publicKey };
+}
+
+function publicKeyFingerprint(publicPem) {
+  return crypto.createHash('sha256').update(publicPem).digest('hex').substring(0, 16);
+}
+
+function publicKeyRawHex(publicPem) {
+  const obj = crypto.createPublicKey({ key: publicPem, format: 'pem', type: 'spki' });
+  const der = obj.export({ type: 'spki', format: 'der' });
+  return Buffer.from(der.subarray(der.length - 32)).toString('hex');
+}
+
+/**
+ * Sign an entitlement record. The signature covers the
+ * canonical JSON of the body (everything except
+ * signature_base64). The signature is base64.
+ */
+function signEntitlement(record, privatePem) {
+  const { signature_base64: _ignore, ...body } = record;
+  const stable = stableStringify(body);
+  const sig = crypto.sign(null, Buffer.from(stable, 'utf8'),
+    crypto.createPrivateKey({ key: privatePem, format: 'pem', type: 'pkcs8' }));
+  return { ...record, signature_base64: sig.toString('base64') };
+}
+
+function verifyEntitlementSignature(record, publicPem) {
+  const { signature_base64, ...body } = record;
+  if (!signature_base64) return { ok: false, reason: 'no signature' };
+  const stable = stableStringify(body);
+  const ok = crypto.verify(
+    null,
+    Buffer.from(stable, 'utf8'),
+    crypto.createPublicKey({ key: publicPem, format: 'pem', type: 'spki' }),
+    Buffer.from(signature_base64, 'base64'),
+  );
+  return { ok, reason: ok ? null : 'signature does not verify' };
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+module.exports = {
+  ensureKeyPair,
+  keyPaths,
+  publicKeyFingerprint,
+  publicKeyRawHex,
+  signEntitlement,
+  verifyEntitlementSignature,
+  stableStringify,
+};

package/src/store.js

@@ -0,0 +1,147 @@
+/**
+ * store.js — entitlement record storage (Story 24)
+ *
+ * Per docs/REMOTE_MODE.md and specs/kdna-entitlement-api.md,
+ * the activation server stores entitlement records. The design
+ * contract calls for SQLite ("zero external dependencies for the
+ * simplest deployment path"). The v0.1.0 implementation uses a
+ * single JSON file (one file per license_id) for the simplest
+ * deployment path. A future version can swap in SQLite without
+ * changing the public API.
+ *
+ * Each record has the shape documented in
+ * specs/kdna-entitlement-api.md §10 (Local Activation File).
+ * The activation server returns the same shape (plus optional
+ * Ed25519 signature) on /activate and /sync endpoints.
+ *
+ * The store is the SOURCE OF TRUTH for entitlement state. The
+ * CLI's local copy at ~/.kdna/licenses/<domain>.json is a
+ * CLIENT cache, not the source of truth. If a client claims
+ * "active" but the server says "revoked", the server wins.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const DEFAULT_DATA_DIR = path.join(
+  process.env.HOME || process.env.USERPROFILE || '.',
+  '.kdna',
+  'activation-server',
+);
+
+function makeStore(dataDir) {
+  if (!dataDir) dataDir = DEFAULT_DATA_DIR;
+  fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+
+  function recordPath(licenseId) {
+    if (!licenseId || !/^[A-Za-z0-9_\-:.]{1,128}$/.test(licenseId)) {
+      throw new Error(`invalid license_id: ${licenseId}`);
+    }
+    return path.join(dataDir, `${licenseId.replace(/[^A-Za-z0-9_\-]/g, '_')}.json`);
+  }
+
+  function get(licenseId) {
+    const p = recordPath(licenseId);
+    if (!fs.existsSync(p)) return null;
+    try {
+      return JSON.parse(fs.readFileSync(p, 'utf8'));
+    } catch (e) {
+      throw new Error(`failed to read ${p}: ${e.message}`);
+    }
+  }
+
+  function getByKey(licenseKey) {
+    // The store is keyed by license_id. The CLI sends both
+    // domain + license_key. We index license_key by scanning
+    // all records (acceptable for self-hosted single-creator
+    // scale; a future version can use a secondary index).
+    const files = fs.readdirSync(dataDir).filter((f) => f.endsWith('.json'));
+    for (const f of files) {
+      try {
+        const rec = JSON.parse(fs.readFileSync(path.join(dataDir, f), 'utf8'));
+        if (rec.license_key === licenseKey) return rec;
+      } catch (_) {
+        // ignore malformed files
+      }
+    }
+    return null;
+  }
+
+  function put(record) {
+    if (!record || !record.license_id) {
+      throw new Error('record.license_id is required');
+    }
+    const p = recordPath(record.license_id);
+    record.updated_at = new Date().toISOString();
+    fs.writeFileSync(p, JSON.stringify(record, null, 2) + '\n', { mode: 0o600 });
+    return record;
+  }
+
+  function list() {
+    const out = [];
+    const files = fs.readdirSync(dataDir).filter((f) => f.endsWith('.json'));
+    for (const f of files) {
+      try {
+        out.push(JSON.parse(fs.readFileSync(path.join(dataDir, f), 'utf8')));
+      } catch (_) {
+        // ignore
+      }
+    }
+    return out;
+  }
+
+  function create({ domain, license_key, license_id, issued_to, require_machine_binding, require_online_check, offline_grace_days, allowed_agents, ttl_days, issued_at }) {
+    if (!domain) throw new Error('domain is required');
+    if (!license_key) throw new Error('license_key is required');
+    if (!license_id) license_id = `lic_${crypto.randomBytes(8).toString('hex')}`;
+
+    const record = {
+      version: '1.0',
+      license_id,
+      license_key,
+      domain,
+      issued_to: issued_to || null,
+      issued_at: issued_at || new Date().toISOString(),
+      expires_at: ttl_days
+        ? new Date(Date.now() + ttl_days * 24 * 60 * 60 * 1000).toISOString()
+        : null,
+      status: 'active',
+      revoked: false,
+      revoked_at: null,
+      revocation_reason: null,
+      require_machine_binding: require_machine_binding !== false,
+      require_online_check: require_online_check !== false,
+      offline_grace_days: typeof offline_grace_days === 'number' ? offline_grace_days : 7,
+      allowed_agents: Array.isArray(allowed_agents) ? allowed_agents : null,
+    };
+    return put(record);
+  }
+
+  function revoke(licenseId, { reason, revoked_by } = {}) {
+    const rec = get(licenseId);
+    if (!rec) return null;
+    rec.status = 'revoked';
+    rec.revoked = true;
+    rec.revoked_at = new Date().toISOString();
+    rec.revocation_reason = reason || null;
+    rec.revoked_by = revoked_by || null;
+    return put(rec);
+  }
+
+  function updateSync(licenseId) {
+    const rec = get(licenseId);
+    if (!rec) return null;
+    rec.last_checked_at = new Date().toISOString();
+    rec.offline_valid_until = new Date(
+      Date.now() + (rec.offline_grace_days || 7) * 24 * 60 * 60 * 1000,
+    ).toISOString();
+    return put(rec);
+  }
+
+  return { get, getByKey, put, list, create, revoke, updateSync, dataDir };
+}
+
+module.exports = { makeStore, DEFAULT_DATA_DIR };