@living-agents/reference 0.0.0-stage → 0.4.10

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# @living-agents/reference
 
-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.
+Reference implementation of the **Living Agents Protocol (LAP)** — the existence layer for always-on AI agents. Implements LIP-1 (Agent Passport), LIP-3 (Scope Algebra v0.2), and LIP-4 (Micro-Core).
+
+**Zero dependencies.** Node ≥ 20 (native Ed25519). Run the suite:
+
+```bash
+node --test test/
+```
+
+The tests verify the deterministic cross-language test vectors in `../output/lip/test-vectors/vectors.json` (generated by a Python script; canonical JSON must match byte-for-byte across languages) plus the adversarial scope-algebra cases from LIP-3 §8:
+
+- passport JWS verification, tamper rejection, wrong-signer rejection, self-ownership rejection path
+- did:key ↔ raw Ed25519 public key round-trip against published hex
+- genesis hash chain reproduction
+- Micro-Core: audience binding, request-signature body+passport binding, act/res/cap invocation checks, signed receipt verification
+- algebra: sub-verb escalation reject (registry DAG), path prefix-escape reject, window-inversion reject, proportional subdivision accept, cross-currency reject, deny-bypass reject (effective sets), sibling budget-replication reject (conservation), depth/decay monotonicity, NFC/case normalization
+
+Modules (`src/`): `crypto-util.js` (b64url, base58, did:key, JCS subset, normalization), `jws.js` (EdDSA compact JWS, passport verification), `algebra.js` (LIP-3 v0.2 subset checker — sound-but-incomplete by design, canonical-order deterministic), `microcore.js` (LIP-4 server invariant, idempotency cache, receipts).
+
+Status: draft v0. Spec texts: `../output/LAP-founding-document.md` and `../output/lip/`. License: Apache-2.0.

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@living-agents/reference",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.10",
+  "description": "Living Agents Protocol (LAP) reference implementation: agent passport (LIP-1), scope algebra (LIP-3), Micro-Core request verification and receipts (LIP-4), RFC 6962 Merkle log, Sigstore Rekor binding. Zero dependencies.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Athar Nouman <atharnouman@gmail.com>",
+  "homepage": "https://atharnouman.github.io/living-agents-protocol/",
+  "repository": { "type": "git", "url": "git+https://github.com/atharnouman/living-agents-protocol.git", "directory": "lap-reference" },
+  "bugs": { "url": "https://github.com/atharnouman/living-agents-protocol/issues" },
+  "keywords": ["ai-agents", "agent-identity", "authorization", "mcp", "a2a", "did", "ed25519", "jws", "rfc9421", "merkle", "sigstore", "protocol"],
+  "engines": { "node": ">=20" },
+  "sideEffects": false,
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./jws": "./src/jws.js",
+    "./algebra": "./src/algebra.js",
+    "./microcore": "./src/microcore.js",
+    "./crypto-util": "./src/crypto-util.js",
+    "./merkle-log": "./src/merkle-log.js",
+    "./rekor": "./src/rekor.js",
+    "./package.json": "./package.json"
+  },
+  "files": ["src/", "README.md", "LICENSE"],
+  "publishConfig": { "access": "public" },
+  "scripts": { "test": "node --test test/" }
+}

package/src/algebra.js

@@ -0,0 +1,252 @@
+// LIP-3 v0.3 — LAP-Core Scope Algebra reference checker.
+// Sound-but-incomplete by design (greedy first-match in canonical order; see LIP-3 §6).
+import { jcs, normalizeUri, normalizeDid } from "./crypto-util.js";
+
+const normId = (s) => (/^did:/i.test(s) ? normalizeDid(s) : normalizeUri(s));
+
+// Seed Action Registry DAG (LIP-3 §2): only registry-declared edges subsume.
+// String prefixing confers NOTHING: e.g. compute:exec:unconfined is deliberately absent.
+export const ACTION_REGISTRY_V0 = {
+  "data:read": ["data:read:public"],
+  "data:write": [],
+  "finance:pay": ["finance:pay:escrow", "finance:pay:release"],
+  "compute:exec": ["compute:exec:sandboxed"],
+  "comm:send": [],
+  "identity:present": [],
+  "governance:revoke": [],
+};
+
+const WINDOW_SECONDS = { utc_hour: 3600, utc_day: 86400 };
+const VALID_WINDOWS = new Set(["tx", "utc_hour", "utc_day", "epoch_total"]);
+const MAX_DEPTH = 16;
+
+// LIP-3 §2 (v0.4): closed resource-scheme set. did/urn are identifiers (used in `cp`), not
+// resources; `git` is reserved for the experimental lap-git commit binding. Every other scheme
+// (http, file, gopher, ...) is refused — the algebra never default-allows an unknown scheme.
+const RES_SCHEMES = new Set(["mcp", "a2a", "ap2", "https", "git"]);
+
+const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+const isStringList = (x) => Array.isArray(x) && x.every((s) => typeof s === "string");
+const show = (x) => { try { return jcs(x); } catch { return JSON.stringify(x) ?? String(x); } };
+
+export function isRegisteredVerb(act, registry = ACTION_REGISTRY_V0) {
+  if (act === "*") return true;
+  if (typeof act !== "string") return false;
+  if (Object.prototype.hasOwnProperty.call(registry, act)) return true;
+  return Object.values(registry).some((children) => children.includes(act));
+}
+
+// LIP-3 §2. Handles both a bare verb string and a verb array (envelope `act[]`),
+// in exact parity with the Python port. Uses value-equality throughout — an array
+// argument must never be compared by reference (round-3 audit F-extra).
+export function dagSubsumes(parentAct, childAct, registry = ACTION_REGISTRY_V0) {
+  const pList = Array.isArray(parentAct) ? parentAct : [parentAct];
+  const cList = Array.isArray(childAct) ? childAct : [childAct];
+  if (![...pList, ...cList].every((a) => isRegisteredVerb(a, registry))) return false;
+  if (pList.includes("*")) return true;
+  const expand = (verb) => {
+    const out = new Set([verb]);
+    for (const ch of registry[verb] ?? []) for (const e of expand(ch)) out.add(e);
+    return out;
+  };
+  const allowed = new Set();
+  for (const p of pList) for (const e of expand(p)) allowed.add(e);
+  return cList.every((c) => allowed.has(c));
+}
+
+function parseRes(res) {
+  if (typeof res !== "string" || res.length === 0) throw new Error("LAP_ERR_RES: resource must be a non-empty string");
+  const norm = normalizeUri(res);
+  // Closed syntax (v0.3): the algebra defines scheme, authority and path — nothing else.
+  // A query, a fragment or an empty interior segment is an unknown construct; never
+  // default-allow an unknown construct (LIP-3 §2).
+  if (/[?#]/.test(norm)) throw new Error("LAP_ERR_RES: query and fragment are not allowed in resource patterns");
+  const m = norm.match(/^([a-z0-9+.-]+):\/\/([^/]+)(\/.*)?$/);
+  if (!m) throw new Error(`LAP_ERR_RES: invalid resource URI: ${res}`);
+  const [, scheme, host, path = ""] = m;
+  if (!RES_SCHEMES.has(scheme)) throw new Error(`LAP_ERR_RES: scheme not in the closed set: ${scheme}`); // F3
+  if (path.includes("//")) throw new Error("LAP_ERR_RES: empty path segment");
+  // F2/F10 (v0.4.10): a resource pattern is decoded, canonical text. Percent-encoding and
+  // backslashes are exactly the forms a downstream proxy resolves AFTER authorization
+  // (`/safe/..\\admin`, `/safe/%252e%252e/admin`), so a pattern MUST contain neither, nor any
+  // control character; with the dot-segment check below this closes the traversal class.
+  if (/[\\%]/.test(path)) throw new Error("LAP_ERR_RES: backslashes and percent-encoding are not allowed in resource patterns");
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f]/.test(path)) throw new Error("LAP_ERR_RES: control characters are not allowed in resource patterns");
+  const segments = path.split("/").filter((s) => s.length > 0);
+  if (segments.includes(".") || segments.includes("..")) {
+    throw new Error("LAP_ERR_RES: dot-segments not allowed");
+  }
+  let wildcard = null;
+  if (segments.at(-1) === "**") { wildcard = "**"; segments.pop(); }
+  else if (segments.at(-1) === "*") { wildcard = "*"; segments.pop(); }
+  if (segments.includes("*") || segments.includes("**")) {
+    throw new Error("LAP_ERR_RES: wildcards are terminal-only");
+  }
+  return { scheme, host, segments, wildcard };
+}
+
+export function pathSubsumes(parentRes, childRes) {
+  const p = parseRes(parentRes);
+  const c = parseRes(childRes);
+  if (p.scheme !== c.scheme || p.host !== c.host) return false;
+  const prefixMatches = p.segments.every((seg, i) => c.segments[i] === seg);
+  if (p.wildcard === "**") {
+    return c.segments.length >= p.segments.length && prefixMatches;
+  }
+  if (p.wildcard === "*") {
+    if (c.wildcard === "**") return false;                                          // never widen
+    if (c.wildcard === "*") return c.segments.length === p.segments.length && prefixMatches; // the same set (v0.3: reflexive)
+    return c.segments.length === p.segments.length + 1 && prefixMatches;
+  }
+  return c.wildcard === null && c.segments.length === p.segments.length && prefixMatches;
+}
+
+const UNIVERSE = Symbol("universe");
+
+export function cpIsValid(cp) {
+  if (cp === undefined || cp === null) return true;
+  if (!isPlainObject(cp)) return false;
+  return (cp.allow === undefined || isStringList(cp.allow)) && (cp.deny === undefined || isStringList(cp.deny));
+}
+
+function effectiveSet(cp = {}) {
+  const allow = (cp.allow ?? []).map(normId);
+  const deny = new Set((cp.deny ?? []).map(normId));
+  return { base: allow.length > 0 ? new Set(allow) : UNIVERSE, deny };
+}
+
+export function counterpartySubsumes(parentCp, childCp) {
+  if (!cpIsValid(parentCp) || !cpIsValid(childCp)) return false;
+  const p = effectiveSet(parentCp ?? {});
+  const c = effectiveSet(childCp ?? {});
+  for (const d of p.deny) if (!c.deny.has(d)) return false;
+  if (p.base === UNIVERSE) return true;
+  if (c.base === UNIVERSE) return false;
+  for (const member of c.base) {
+    if (c.deny.has(member)) continue;
+    if (!p.base.has(member) || p.deny.has(member)) return false;
+  }
+  return true;
+}
+
+// F8: caps must be non-negative safe integers with max_per_tx <= max_cumulative,
+// a real unit, and a known window. Returns false (never throws) so direct callers
+// of capSubsumes/scopeSubsumes fail closed; verifyEnvelopeAttenuation throws early.
+export function capIsValid(cap) {
+  if (cap === undefined || cap === null) return true;
+  if (!isPlainObject(cap)) return false;
+  for (const f of ["max_per_tx", "max_cumulative"]) {
+    const v = cap[f];
+    if (!Number.isSafeInteger(v) || v < 0) return false;
+  }
+  if (cap.max_per_tx > cap.max_cumulative) return false;
+  if (typeof cap.unit !== "string" || cap.unit.length === 0) return false;
+  if (!VALID_WINDOWS.has(cap.window)) return false;
+  return true;
+}
+
+// v0.3: window scaling is exact-integer arithmetic. Double arithmetic (value × 3600 / 86400)
+// rounds above ~1e11 and diverged from the Python port by one unit in ~5% of large-value
+// cases — found by the differential fuzzer. Inputs are safe integers (F8), so BigInt is exact.
+const scaleFloor = (value, num, den) => (BigInt(value) * BigInt(num)) / BigInt(den);
+
+// LIP-3 §4: two-dimensional cap rule. Fails closed on any invalid cap (F8).
+export function capSubsumes(parentCap, childCap) {
+  if (parentCap === undefined || parentCap === null) return true;
+  if (childCap === undefined || childCap === null) return false;
+  if (!capIsValid(parentCap) || !capIsValid(childCap)) return false;
+  if (childCap.unit !== parentCap.unit) return false;
+  if (childCap.max_per_tx > parentCap.max_per_tx) return false;
+  const pw = parentCap.window;
+  const cw = childCap.window;
+  if (pw === "tx") {
+    // tightened (audit F7): a tx parent admits only a tx child — a differently-based
+    // child window would rate-expand the parent's per-transaction budget.
+    return cw === "tx" && childCap.max_cumulative <= parentCap.max_cumulative;
+  }
+  if (pw === "epoch_total") {
+    return cw === "epoch_total" && childCap.max_cumulative <= parentCap.max_cumulative;
+  }
+  if (cw === "tx" || cw === "epoch_total") return false;
+  const pSec = WINDOW_SECONDS[pw];
+  const cSec = WINDOW_SECONDS[cw];
+  if (!pSec || !cSec || cSec > pSec || pSec % cSec !== 0) return false;
+  return BigInt(childCap.max_cumulative) <= scaleFloor(parentCap.max_cumulative, cSec, pSec);
+}
+
+// LIP-3 §5 (v0.3): shape validation precedes every comparison. Returns false (never throws)
+// so a direct caller fails closed; verifyEnvelopeAttenuation throws LAP_ERR_SCOPE_SCHEMA.
+// Found by the fuzzer: malformed scopes used to surface TypeErrors from deep inside the
+// comparison, and a missing `act` compared as "grants nothing ⊆ grants nothing" in one port.
+export function scopeIsValid(scope) {
+  if (!isPlainObject(scope)) return false;
+  if (typeof scope.v !== "string") return false;
+  if (!(typeof scope.act === "string" || isStringList(scope.act))) return false;
+  if (typeof scope.res !== "string") return false;
+  if (!cpIsValid(scope.cp) || !capIsValid(scope.cap)) return false;
+  for (const f of ["depth", "decay_max_sec"]) {
+    const v = scope[f];
+    if (v !== undefined && !(Number.isSafeInteger(v) && v >= 0)) return false;
+  }
+  if (scope.depth !== undefined && scope.depth > MAX_DEPTH) return false;
+  return true;
+}
+
+// F9: caps are a conjunct of the subset relation — a direct caller (a policy engine)
+// must never get a cap-blind "true". scopeSubsumes now includes capSubsumes.
+export function scopeSubsumes(parent, child, registry = ACTION_REGISTRY_V0) {
+  if (!scopeIsValid(parent) || !scopeIsValid(child)) return false;
+  return (
+    parent.v === "lap-scope-v0" &&
+    child.v === "lap-scope-v0" &&
+    dagSubsumes(parent.act, child.act, registry) &&
+    pathSubsumes(parent.res, child.res) &&
+    counterpartySubsumes(parent.cp, child.cp) &&
+    capSubsumes(parent.cap, child.cap) &&
+    (parent.depth === undefined || (child.depth !== undefined && child.depth <= parent.depth - 1)) &&
+    (parent.decay_max_sec === undefined || (child.decay_max_sec !== undefined && child.decay_max_sec <= parent.decay_max_sec))
+  );
+}
+
+// F7: debit the child's allocation expressed in the PARENT window's units, so a
+// smaller-window child cannot multiply the parent's budget across sub-buckets.
+// A utc_hour child of a utc_day parent debits max_cumulative × 24, not × 1. (BigInt: exact.)
+function windowDebit(parentCap, childCap) {
+  const pSec = WINDOW_SECONDS[parentCap.window];
+  const cSec = WINDOW_SECONDS[childCap.window];
+  if (pSec && cSec) return scaleFloor(childCap.max_cumulative, pSec, cSec);
+  return BigInt(childCap.max_cumulative); // same-basis (tx/epoch_total): no scaling
+}
+
+// LIP-3 §6: envelope-level verification with budget conservation.
+// Deterministic: children and parents evaluated in canonical (JCS) sorted order.
+export function verifyEnvelopeAttenuation(parentScopes, childScopes, registry = ACTION_REGISTRY_V0) {
+  if (!Array.isArray(parentScopes) || !Array.isArray(childScopes)) {
+    throw new Error("LAP_ERR_SCOPE_SCHEMA: scope sets must be arrays");
+  }
+  for (const s of [...parentScopes, ...childScopes]) {
+    if (!capIsValid(isPlainObject(s) ? s.cap : undefined)) throw new Error(`LAP_ERR_CAP_SCHEMA: invalid cap in ${show(s)}`);
+    if (!scopeIsValid(s)) throw new Error(`LAP_ERR_SCOPE_SCHEMA: malformed scope ${show(s)}`);
+  }
+  const canonical = (arr) => [...arr].sort((a, b) => (jcs(a) < jcs(b) ? -1 : 1));
+  const parents = canonical(parentScopes);
+  const children = canonical(childScopes);
+  const remaining = parents.map((p) => (p.cap ? BigInt(p.cap.max_cumulative) : null));
+  for (const c of children) {
+    let matched = false;
+    for (let i = 0; i < parents.length; i++) {
+      const p = parents[i];
+      if (!scopeSubsumes(p, c, registry)) continue;
+      if (p.cap) {
+        const debit = windowDebit(p.cap, c.cap);
+        if (debit > remaining[i]) continue;
+        remaining[i] -= debit;
+      }
+      matched = true;
+      break;
+    }
+    if (!matched) return { ok: false, rejected: c };
+  }
+  return { ok: true };
+}

package/src/crypto-util.js

@@ -0,0 +1,148 @@
+import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
+
+const B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+// DER SPKI header for a raw Ed25519 public key (RFC 8410)
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+const B64URL_ALPHABET = /^[A-Za-z0-9_-]*$/;
+
+// STRICT base64url (RFC 4648 §5, unpadded; §3.5 canonical trailing bits). Lenient decoding lets
+// one signature have many textual forms — 'A'→'B' as the final character of an Ed25519 signature
+// changes padding bits only and still verifies — so anything keyed by the TEXT (passport hashes,
+// dedup, denylists, transparency-log entries) could be evaded by re-encoding. Reject instead.
+export function b64urlDecode(s) {
+  if (typeof s !== "string" || !B64URL_ALPHABET.test(s) || s.length % 4 === 1) {
+    throw new Error("LAP_ERR_ENCODING: invalid base64url");
+  }
+  const buf = Buffer.from(s, "base64url");
+  if (buf.toString("base64url") !== s) throw new Error("LAP_ERR_ENCODING: non-canonical base64url");
+  return buf;
+}
+
+export function b64urlEncode(buf) {
+  return Buffer.from(buf).toString("base64url");
+}
+
+export function sha256Hex(data) {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+export function sha256B64url(data) {
+  return b64urlEncode(createHash("sha256").update(data).digest());
+}
+
+export function b58Encode(buf) {
+  let n = BigInt("0x" + (Buffer.from(buf).toString("hex") || "0"));
+  let s = "";
+  while (n > 0n) {
+    const r = n % 58n;
+    n /= 58n;
+    s = B58[Number(r)] + s;
+  }
+  let pad = 0;
+  for (const byte of buf) {
+    if (byte === 0) pad++;
+    else break;
+  }
+  return "1".repeat(pad) + s;
+}
+
+export function b58Decode(s) {
+  if (!s || s.length === 0) return Buffer.alloc(0);
+  let n = 0n;
+  for (const ch of s) {
+    const v = B58.indexOf(ch);
+    if (v < 0) throw new Error(`invalid base58 character: ${ch}`);
+    n = n * 58n + BigInt(v);
+  }
+  let pad = 0;
+  for (const ch of s) {
+    if (ch === "1") pad++;
+    else break;
+  }
+  if (n === 0n) return Buffer.alloc(pad);
+  let hex = n.toString(16);
+  if (hex.length % 2) hex = "0" + hex;
+  const out = Buffer.from(hex, "hex");
+  return pad ? Buffer.concat([Buffer.alloc(pad), out]) : out;
+}
+
+// did:key:z6Mk... -> 32-byte raw Ed25519 public key
+export function didKeyToRawPublicKey(did) {
+  if (!did.startsWith("did:key:z")) throw new Error(`unsupported DID method: ${did}`);
+  const multibase = did.slice("did:key:z".length);
+  // F12: bound input BEFORE base58 decoding — an ed25519 did:key multibase is ~46-48
+  // chars; `iss`/`agentDid` are attacker-controlled and decoded pre-auth, so an
+  // unbounded string would drive O(n^2) BigInt work (CPU-exhaustion DoS).
+  if (multibase.length > 48) throw new Error("LAP_ERR_DID: multibase too long for ed25519 did:key");
+  const decoded = b58Decode(multibase);
+  if (decoded[0] !== 0xed || decoded[1] !== 0x01) throw new Error("not an ed25519-pub did:key");
+  const raw = decoded.subarray(2);
+  if (raw.length !== 32) throw new Error(`bad key length: ${raw.length}`);
+  return raw;
+}
+
+export function publicKeyFromRaw(raw32) {
+  return createPublicKey({
+    key: Buffer.concat([ED25519_SPKI_PREFIX, raw32]),
+    format: "der",
+    type: "spki",
+  });
+}
+
+export function publicKeyFromDid(did) {
+  return publicKeyFromRaw(didKeyToRawPublicKey(did));
+}
+
+// 32-byte raw Ed25519 public key -> did:key:z6Mk...
+export function didKeyFromRawPublicKey(raw32) {
+  return "did:key:z" + b58Encode(Buffer.concat([Buffer.from([0xed, 0x01]), raw32]));
+}
+
+export function rawPublicKeyFromKeyObject(publicKey) {
+  const der = publicKey.export({ format: "der", type: "spki" });
+  return der.subarray(der.length - 32);
+}
+
+export function verifyEd25519(publicKey, data, signature) {
+  return cryptoVerify(null, Buffer.from(data), publicKey, signature);
+}
+
+// DID-safe normalization: NFC + lowercase the "did:method:" prefix ONLY.
+// The method-specific id is case-sensitive (base58 in did:key) and MUST NOT be
+// case-folded — lowercasing it would corrupt the key. (Round-3 triage note: the
+// reviewer's proposed fix of running DIDs through normalizeUri would do exactly that.)
+export function normalizeDid(did) {
+  const s = did.normalize("NFC");
+  const m = s.match(/^did:([A-Za-z0-9]+):(.+)$/i);   // prefix case-insensitive, id case preserved (parity with the Python port)
+  if (!m) return s;
+  return "did:" + m[1].toLowerCase() + ":" + m[2];
+}
+
+// LIP-1 §3 string normalization for resource URIs: NFC + lowercase scheme/host.
+// Do NOT use on DIDs — use normalizeDid (host-lowercasing corrupts did:key ids).
+export function normalizeUri(uri) {
+  const s = uri.normalize("NFC");
+  const m = s.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):(\/\/)?([^/]*)(.*)$/);
+  if (!m) return s;
+  const [, scheme, slashes = "", host, rest] = m;
+  return scheme.toLowerCase() + ":" + slashes + host.toLowerCase() + rest;
+}
+
+// JCS-compatible canonical JSON for the LAP data subset (ASCII strings, integers,
+// objects, arrays, null, booleans). Matches Python json.dumps(sort_keys=True,
+// separators=(",",":")) for this subset.
+export function jcs(value) {
+  if (value === null || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value === "number") {
+    if (!Number.isInteger(value)) throw new Error("JCS subset: integers only");
+    return String(value);
+  }
+  if (typeof value === "string") return JSON.stringify(value);
+  if (Array.isArray(value)) return "[" + value.map(jcs).join(",") + "]";
+  if (typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return "{" + keys.map((k) => JSON.stringify(k) + ":" + jcs(value[k])).join(",") + "}";
+  }
+  throw new Error(`JCS subset: unsupported type ${typeof value}`);
+}

package/src/index.js

@@ -0,0 +1,8 @@
+// Living Agents Protocol — reference implementation, root entry point.
+// Subpath imports remain available: "@living-agents/reference/microcore", ".../algebra", etc.
+export * from "./crypto-util.js";
+export * from "./jws.js";
+export * from "./algebra.js";
+export * from "./microcore.js";
+export * from "./merkle-log.js";
+export * from "./rekor.js";

package/src/jws.js

@@ -0,0 +1,65 @@
+import { sign as cryptoSign } from "node:crypto";
+import { b64urlDecode, b64urlEncode, jcs, normalizeDid, publicKeyFromDid, verifyEd25519 } from "./crypto-util.js";
+
+// Produce a compact EdDSA JWS over the JCS canonical form of `payload`.
+export function signJws(payload, privateKey, kid, typ = "lap-passport+jwt") {
+  const header = { alg: "EdDSA", kid, typ };
+  const input = b64urlEncode(Buffer.from(jcs(header))) + "." + b64urlEncode(Buffer.from(jcs(payload)));
+  const sig = cryptoSign(null, Buffer.from(input), privateKey);
+  return input + "." + b64urlEncode(sig);
+}
+
+export const SKEW_SECONDS = 60; // LIP-1 §2 default clock-skew tolerance
+
+function parseJwsJson(b64, what) {
+  // F7: a valid-base64url-but-invalid-JSON segment must be a typed protocol error, not a
+  // raw language SyntaxError leaking out of a verifier.
+  try { return JSON.parse(b64urlDecode(b64).toString()); }
+  catch (e) { throw new Error(`LAP_ERR_SIG: malformed JWS ${what} (${e.message})`); }
+}
+
+export function decodeJws(token) {
+  if (typeof token !== "string") throw new Error("LAP_ERR_SIG: token must be a string"); // F8
+  const parts = token.split(".");
+  if (parts.length !== 3) throw new Error("LAP_ERR_SIG: not a compact JWS");
+  const [h, p, s] = parts;
+  return {
+    header: parseJwsJson(h, "header"),
+    payload: parseJwsJson(p, "payload"),
+    signature: b64urlDecode(s),
+    signingInput: Buffer.from(h + "." + p),
+  };
+}
+
+// Verify a compact EdDSA JWS whose signer is identified by `signerDid` (did:key).
+export function verifyJws(token, signerDid) {
+  const { header, payload, signature, signingInput } = decodeJws(token);
+  if (header.alg !== "EdDSA") throw new Error(`LAP_ERR_SIG: alg ${header.alg}`);
+  const key = publicKeyFromDid(signerDid);
+  if (!verifyEd25519(key, signingInput, signature)) throw new Error("LAP_ERR_SIG: signature invalid");
+  return { header, payload };
+}
+
+export function checkTimeWindow(payload, now = Math.floor(Date.now() / 1000)) {
+  if (typeof payload.iat !== "number") throw new Error("LAP_ERR_EXPIRED: iat missing");
+  if (typeof payload.exp !== "number") throw new Error("LAP_ERR_EXPIRED: exp missing");
+  if (now < payload.iat - SKEW_SECONDS || now > payload.exp + SKEW_SECONDS) {
+    throw new Error("LAP_ERR_EXPIRED");
+  }
+}
+
+// LIP-1 §6 passport verification (the vector-testable subset: steps 1-5 of nine;
+// proof-class credentials, revocation endpoints, and registration proofs need
+// network context and live in the higher-level verifier).
+export function verifyPassport(token, { now } = {}) {
+  const { header, payload } = decodeJws(token);
+  if (payload.v !== "lip1-v0") throw new Error("LAP_ERR_VERSION");
+  if (header.alg !== "EdDSA") throw new Error(`LAP_ERR_SIG: alg ${header.alg}`);
+  const principalDid = payload.principal?.id ? normalizeDid(payload.principal.id) : null;
+  const agentDid = payload.id ? normalizeDid(payload.id) : null;
+  if (!principalDid) throw new Error("LAP_ERR_SELF_OWNED: principal missing");
+  if (principalDid === agentDid) throw new Error("LAP_ERR_SELF_OWNED");
+  verifyJws(token, principalDid);
+  checkTimeWindow(payload, now);
+  return payload;
+}

package/src/merkle-log.js

@@ -0,0 +1,78 @@
+// Minimal append-only Merkle transparency log (RFC 6962 hashing convention) —
+// the local building block of a LAP Agent Transparency Log (SCITT-profile, spec §14.5/§19).
+// Plus salted blinded principal commitments (GDPR rule, spec §14.5): the salt stays
+// off-log with the principal; erasure = salt destruction.
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+
+const h = (...bufs) => {
+  const c = createHash("sha256");
+  for (const b of bufs) c.update(b);
+  return c.digest();
+};
+const LEAF = Buffer.from([0x00]);
+const NODE = Buffer.from([0x01]);
+
+export function leafHash(dataBuf) {
+  return h(LEAF, dataBuf);
+}
+
+export function saltedCommitment(principalDid, saltHex = randomBytes(16).toString("hex")) {
+  if (saltHex.length < 32) throw new Error("salt must be >=128 bits");
+  const commitment = h(Buffer.from(saltHex, "hex"), Buffer.from(principalDid)).toString("hex");
+  return { commitment, saltHex }; // saltHex is held OFF-log by the principal
+}
+
+export function verifyCommitment(commitmentHex, saltHex, principalDid) {
+  const a = Buffer.from(saltedCommitment(principalDid, saltHex).commitment, "hex");
+  const b = Buffer.from(commitmentHex, "hex");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+export class MerkleLog {
+  constructor(name) {
+    this.name = name;
+    this.leaves = []; // leaf hashes (Buffers)
+  }
+  get size() { return this.leaves.length; }
+
+  append(dataBuf) {
+    this.leaves.push(leafHash(dataBuf));
+    return this.size - 1;
+  }
+
+  // RFC 6962 Merkle Tree Hash over leaves[lo, hi)
+  #mth(lo, hi) {
+    const n = hi - lo;
+    if (n === 0) return h();
+    if (n === 1) return this.leaves[lo];
+    let k = 1;
+    while (k * 2 < n) k *= 2;
+    return h(NODE, this.#mth(lo, lo + k), this.#mth(lo + k, hi));
+  }
+  root() { return this.#mth(0, this.size).toString("hex"); }
+
+  // RFC 6962 audit path for leaf at index m within leaves[lo, hi)
+  #path(m, lo, hi) {
+    const n = hi - lo;
+    if (n <= 1) return [];
+    let k = 1;
+    while (k * 2 < n) k *= 2;
+    if (m - lo < k) {
+      return [...this.#path(m, lo, lo + k), { side: "right", hash: this.#mth(lo + k, hi).toString("hex") }];
+    }
+    return [...this.#path(m, lo + k, hi), { side: "left", hash: this.#mth(lo, lo + k).toString("hex") }];
+  }
+  inclusionProof(index) {
+    if (index < 0 || index >= this.size) throw new Error("index out of range");
+    return { log: this.name, index, size: this.size, root: this.root(), path: this.#path(index, 0, this.size) };
+  }
+}
+
+export function verifyInclusion(dataBuf, proof) {
+  let cur = leafHash(dataBuf);
+  for (const step of proof.path) {
+    const sib = Buffer.from(step.hash, "hex");
+    cur = step.side === "left" ? h(NODE, sib, cur) : h(NODE, cur, sib);
+  }
+  return cur.toString("hex") === proof.root;
+}

package/src/microcore.js

@@ -0,0 +1,125 @@
+// LIP-4 — Micro-Core server-side verification invariant (§2), transport-agnostic core.
+import { timingSafeEqual } from "node:crypto";
+import { publicKeyFromDid, verifyEd25519, b64urlDecode, sha256Hex, sha256B64url, normalizeUri, normalizeDid } from "./crypto-util.js";
+import { decodeJws, verifyJws, checkTimeWindow } from "./jws.js";
+import { pathSubsumes } from "./algebra.js";
+
+const PROOF_CLASS_ORDER = ["self-asserted", "domain-validated", "org-validated", "gov-validated"];
+
+// Step 1: verify the principal-signed passport JWT, audience, and time window.
+// F4: `expectedAud` is MANDATORY — a missing audience is fail-open cross-server replay.
+// F1: `allowedIssuers` / `minProofClass` let a server refuse self-asserted or unknown
+// principals. A valid passport proves identity + envelope integrity; it is NOT by itself
+// authority over a server-owned resource — the server MUST apply its own trust policy.
+export function verifyMicroCorePassport(passportJwt, { expectedAud, allowedIssuers, minProofClass, now } = {}) {
+  if (!expectedAud) throw new Error("LAP_ERR_AUDIENCE: expectedAud (this server's identity) is required");
+  const iss = decodeJws(passportJwt).payload.iss; // F7: typed LAP_ERR_SIG on a malformed token, never a raw SyntaxError
+  if (!iss) throw new Error("LAP_ERR_PASSPORT: iss missing");
+  const { payload } = verifyJws(passportJwt, iss); // proves the presenter controls iss's key
+  if (!payload.aud) throw new Error("LAP_ERR_AUDIENCE: aud missing");
+  if (normalizeUri(payload.aud) !== normalizeUri(expectedAud)) throw new Error("LAP_ERR_AUDIENCE");
+  checkTimeWindow(payload, now);
+  if (!payload.lap?.envelope) throw new Error("LAP_ERR_PASSPORT_SIG: envelope missing");
+  if (allowedIssuers && !allowedIssuers.map(normalizeDid).includes(normalizeDid(iss))) {
+    throw new Error("LAP_ERR_ISSUER: issuer not in server allow-list");
+  }
+  if (minProofClass) {
+    const have = PROOF_CLASS_ORDER.indexOf(payload.lap.proof_class);
+    if (have < 0 || have < PROOF_CLASS_ORDER.indexOf(minProofClass)) {
+      throw new Error("LAP_ERR_PROOF_CLASS: below required floor");
+    }
+  }
+  return payload;
+}
+
+// Step 2: verify the AGENT's request signature. F2: the verification key is derived
+// from the verified passport's `sub` (holder-of-key) — never from a caller-supplied
+// DID, or a captured passport plus any attacker keypair would pass. F3: the mandatory
+// RFC 9421 covered components must be present, and are compared to the server-observed
+// method/target when those are supplied.
+export function verifyRequestSignature({ passportJwt, sub, signatureBase, signatureB64url, requestBody, expectedMethod, expectedTarget }) {
+  if (!sub) throw new Error("LAP_ERR_REQ_SIG: sub (verified passport subject) required");
+  const key = publicKeyFromDid(sub);
+  if (!verifyEd25519(key, Buffer.from(signatureBase), b64urlDecode(signatureB64url))) {
+    throw new Error("LAP_ERR_REQ_SIG");
+  }
+  const lines = signatureBase.split("\n");
+  const findLine = (prefix) => lines.find((l) => l.startsWith(prefix));
+  for (const comp of ['"@method":', '"@target-uri":', '"content-digest":', '"lap-passport-hash":', '"@signature-params":']) {
+    if (!findLine(comp)) throw new Error(`LAP_ERR_SIG_PARAMS: missing covered component ${comp}`);
+  }
+  const expectedDigest = `"content-digest": sha-256=:${sha256B64url(requestBody)}:`;
+  if (!lines.includes(expectedDigest)) throw new Error("LAP_ERR_DIGEST");
+  const expectedPassportLine = `"lap-passport-hash": sha256:${sha256Hex(passportJwt)}`;
+  if (!lines.includes(expectedPassportLine)) throw new Error("LAP_ERR_DIGEST: passport hash");
+  if (expectedMethod !== undefined && findLine('"@method":') !== `"@method": ${expectedMethod}`) {
+    throw new Error("LAP_ERR_METHOD: signed method does not match transport");
+  }
+  if (expectedTarget !== undefined && findLine('"@target-uri":') !== `"@target-uri": ${expectedTarget}`) {
+    throw new Error("LAP_ERR_TARGET: signed target does not match transport");
+  }
+  return true;
+}
+
+// Steps 3-4: the invoked operation must match the envelope (registered-verb equality,
+// segment-wise resource match, per-transaction cap in the exact unit).
+export function checkInvocation(envelope, { act, resource, amount, unit }) {
+  if (envelope.act.includes("*")) throw new Error("LAP_ERR_ACT: wildcard not allowed in Micro-Core envelopes");
+  if (!envelope.act.includes(act)) throw new Error("LAP_ERR_ACT");
+  if (!pathSubsumes(envelope.res, resource)) throw new Error("LAP_ERR_RES");
+  if (envelope.cap) {
+    // F5 parity: a capped tool with an indeterminable amount MUST fail closed.
+    if (amount === undefined || amount === null) throw new Error("LAP_ERR_CAP: capped operation requires an amount");
+    if (unit !== envelope.cap.unit) throw new Error("LAP_ERR_CAP: unit");
+    if (amount > envelope.cap.max_per_tx) throw new Error("LAP_ERR_CAP");
+  }
+  return true;
+}
+
+// Step 5 helper: idempotency cache keyed by (agent, key). NUL separator prevents
+// key-splicing collisions. F6: `claim()` reserves atomically within one process,
+// closing the check-then-await-then-store race. NOT distributed — production
+// deployments MUST back this with a shared store (Redis SET NX / DB unique
+// constraint) or a load balancer replays a signed key once per replica.
+export function makeIdempotencyCache() {
+  const seen = new Map();
+  const k = (agentDid, idempotencyKey) => `${agentDid}\u0000${idempotencyKey}`;
+  return {
+    // F1 (v0.4.10): three-state atomic reservation. A binary null return could not tell a
+    // FRESH reservation from an IN-FLIGHT one, so two concurrent mutating requests both saw
+    // "free" and both executed. Callers proceed ONLY on {status:"reserved"}; {status:"in_flight"}
+    // is a duplicate to reject (e.g. HTTP 409); {status:"completed"} returns the cached receipt.
+    claim(agentDid, idempotencyKey) {
+      const key = k(agentDid, idempotencyKey);
+      if (!seen.has(key)) { seen.set(key, null); return { status: "reserved" }; }
+      const receipt = seen.get(key);
+      return receipt === null ? { status: "in_flight" } : { status: "completed", receipt };
+    },
+    complete(agentDid, idempotencyKey, receipt) {
+      seen.set(k(agentDid, idempotencyKey), receipt);
+    },
+    check(agentDid, idempotencyKey) {
+      return seen.get(k(agentDid, idempotencyKey));
+    },
+    store(agentDid, idempotencyKey, receipt) {
+      seen.set(k(agentDid, idempotencyKey), receipt);
+    },
+  };
+}
+
+// LIP-4 §3: verify a tripartite receipt line against the tool server's key.
+export function verifyReceipt({ receiptBase, receiptSignatureB64url, serverDid, requestBody, responseBody }) {
+  const key = publicKeyFromDid(serverDid);
+  if (!verifyEd25519(key, Buffer.from(receiptBase), b64urlDecode(receiptSignatureB64url))) {
+    throw new Error("LAP_ERR_RECEIPT_SIG");
+  }
+  const [reqPart, respPart] = [receiptBase.split(":").slice(0, 2).join(":"), receiptBase.split(":").slice(2).join(":")];
+  const tse = (a, b) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+  if (requestBody !== undefined && !tse(reqPart, `sha256:${sha256Hex(requestBody)}`)) {
+    throw new Error("LAP_ERR_RECEIPT: request hash mismatch");
+  }
+  if (responseBody !== undefined && !tse(respPart, `sha256:${sha256Hex(responseBody)}`)) {
+    throw new Error("LAP_ERR_RECEIPT: response hash mismatch");
+  }
+  return true;
+}

package/src/rekor.js

@@ -0,0 +1,133 @@
+// Sigstore Rekor binding — registers a LAP Genesis Record in the PUBLIC Rekor
+// transparency log and verifies the result with LAP's own RFC 6962 code.
+//
+// This turns "registration is self-attested" (the demo's honest caveat) into
+// "registered in an append-only public log anyone can audit" (spec §14.5 / §19:
+// the Agent Transparency Log pattern, here instantiated on an existing neutral log).
+//
+// What gets logged: the canonical genesis JSON, the principal's Ed25519 signature
+// over it, and the principal's public key (PEM). Rekor verifies the signature before
+// admitting the entry, then returns an inclusion proof against its Merkle root and a
+// Signed Entry Timestamp (SET) under Rekor's own key. We verify all three locally.
+import { createHash, createPublicKey, createVerify, sign, verify } from "node:crypto";
+import { jcs, sha256Hex, didKeyFromRawPublicKey, rawPublicKeyFromKeyObject } from "./crypto-util.js";
+import { leafHash } from "./merkle-log.js";
+
+export const REKOR_PUBLIC = "https://rekor.sigstore.dev";
+export const searchUrl = (logIndex) => `https://search.sigstore.dev/?logIndex=${logIndex}`;
+
+// ---------- building the entry ----------
+// `rekord` (x509 signature format) carries the full content, so Rekor can verify a
+// pure-Ed25519 signature over it (hashedrekord cannot, since Ed25519 signs messages,
+// not digests).
+export function buildGenesisEntry(genesisRecord, principalPrivateKey) {
+  const content = Buffer.from(jcs(genesisRecord));
+  const signature = sign(null, content, principalPrivateKey);
+  const pem = createPublicKey(principalPrivateKey).export({ type: "spki", format: "pem" });
+  return {
+    apiVersion: "0.0.1",
+    kind: "rekord",
+    spec: {
+      data: { content: content.toString("base64") },
+      signature: {
+        format: "x509",
+        content: signature.toString("base64"),
+        publicKey: { content: Buffer.from(pem).toString("base64") },
+      },
+    },
+  };
+}
+
+// ---------- talking to the log ----------
+const normalize = (map) => { const [uuid, e] = Object.entries(map)[0]; return { uuid, ...e }; };
+
+export async function submitEntry(entry, base = REKOR_PUBLIC) {
+  const r = await fetch(`${base}/api/v1/log/entries`, {
+    method: "POST", headers: { "content-type": "application/json", accept: "application/json" }, body: JSON.stringify(entry),
+  });
+  if (r.status === 409) { // identical entry already logged: idempotent — fetch it
+    const loc = r.headers.get("location") || "";
+    return fetchEntry(loc.split("/").pop(), base);
+  }
+  const text = await r.text();
+  if (r.status !== 201) throw new Error(`LAP_ERR_REKOR_SUBMIT: HTTP ${r.status}: ${text.slice(0, 300)}`);
+  return normalize(JSON.parse(text));
+}
+
+export async function fetchEntry(uuidOrIndex, base = REKOR_PUBLIC) {
+  const byIndex = /^\d+$/.test(String(uuidOrIndex));
+  const url = byIndex ? `${base}/api/v1/log/entries?logIndex=${uuidOrIndex}` : `${base}/api/v1/log/entries/${uuidOrIndex}`;
+  const r = await fetch(url, { headers: { accept: "application/json" } });
+  if (!r.ok) throw new Error(`LAP_ERR_REKOR_FETCH: HTTP ${r.status}`);
+  return normalize(await r.json());
+}
+
+export async function fetchRekorPublicKey(base = REKOR_PUBLIC) {
+  const r = await fetch(`${base}/api/v1/log/publicKey`);
+  if (!r.ok) throw new Error(`LAP_ERR_REKOR_KEY: HTTP ${r.status}`);
+  return await r.text(); // PEM (ECDSA P-256)
+}
+
+// ---------- RFC 6962 verification, LAP-side ----------
+const nodeHash = (l, r) => createHash("sha256").update(Buffer.from([0x01])).update(l).update(r).digest();
+const bitLen = (x) => (x === 0n ? 0 : x.toString(2).length);
+const popcount = (x) => x.toString(2).split("1").length - 1;
+
+// Root reconstruction from a side-less audit path (RFC 6962 §2.1.1). This is the
+// compact "inner + border" formulation used by Trillian and Rekor's own verifier;
+// orientation at each level is derived from (index, size) rather than carried.
+export function rootFromInclusionProof(leaf, index, size, hashes) {
+  if (index >= size) throw new Error("LAP_ERR_REKOR_PROOF: index >= treeSize");
+  const inner = bitLen(BigInt(index) ^ BigInt(size - 1));
+  const border = popcount(BigInt(index) >> BigInt(inner));
+  if (hashes.length !== inner + border) throw new Error(`LAP_ERR_REKOR_PROOF: expected ${inner + border} hashes, got ${hashes.length}`);
+  let seed = leaf;
+  for (let i = 0; i < inner; i++) {
+    const h = Buffer.from(hashes[i], "hex");
+    seed = ((BigInt(index) >> BigInt(i)) & 1n) === 0n ? nodeHash(seed, h) : nodeHash(h, seed);
+  }
+  for (let i = inner; i < hashes.length; i++) seed = nodeHash(Buffer.from(hashes[i], "hex"), seed);
+  return seed;
+}
+
+// Verify a Rekor entry end to end:
+//  1. inclusion — SHA256(0x00||body) chains to the log's root through the audit path;
+//  2. substance — the logged key is the expected principal, the logged content is the
+//     expected genesis, and the logged signature verifies (Rekor is not trusted for this);
+//  3. SET — Rekor's ECDSA-P256 signature over {body, integratedTime, logID, logIndex}.
+export function verifyEntry(entry, { expectedPrincipalDid, expectedGenesis, rekorPublicKeyPem } = {}) {
+  const body = Buffer.from(entry.body, "base64");
+  const leaf = leafHash(body);
+  const p = entry.verification?.inclusionProof;
+  if (!p) throw new Error("LAP_ERR_REKOR_PROOF: entry carries no inclusion proof (not yet integrated?)");
+  const root = rootFromInclusionProof(leaf, p.logIndex, p.treeSize, p.hashes).toString("hex");
+  if (root !== p.rootHash) throw new Error("LAP_ERR_REKOR_INCLUSION: reconstructed root does not match the log root");
+
+  const spec = JSON.parse(body.toString()).spec;
+  const key = createPublicKey(Buffer.from(spec.signature.publicKey.content, "base64").toString());
+  const principalDid = didKeyFromRawPublicKey(rawPublicKeyFromKeyObject(key));
+  if (expectedPrincipalDid && principalDid !== expectedPrincipalDid) throw new Error("LAP_ERR_REKOR_KEY: logged key is not the expected principal");
+  // Rekor's canonical body keeps only the content's HASH (spec.data.hash) plus the
+  // signature and key — the content itself is not stored. Substance is therefore
+  // re-verified against the caller's expected genesis, never taken from the log.
+  const loggedHash = spec.data?.hash?.value ?? (spec.data?.content ? sha256Hex(Buffer.from(spec.data.content, "base64")) : null);
+  if (!loggedHash) throw new Error("LAP_ERR_REKOR_CONTENT: entry carries neither a data hash nor content");
+  let signatureVerified = null;
+  if (expectedGenesis) {
+    const content = Buffer.from(jcs(expectedGenesis));
+    if (sha256Hex(content) !== loggedHash) throw new Error("LAP_ERR_REKOR_CONTENT: logged hash is not the expected genesis record");
+    signatureVerified = verify(null, content, key, Buffer.from(spec.signature.content, "base64"));
+    if (!signatureVerified) throw new Error("LAP_ERR_REKOR_SIG: logged signature does not verify over the expected genesis");
+  }
+
+  let setVerified = null;
+  if (rekorPublicKeyPem) {
+    const payload = jcs({ body: entry.body, integratedTime: entry.integratedTime, logID: entry.logID, logIndex: entry.logIndex });
+    setVerified = createVerify("sha256").update(payload).verify(rekorPublicKeyPem, Buffer.from(entry.verification.signedEntryTimestamp, "base64"));
+    if (!setVerified) throw new Error("LAP_ERR_REKOR_SET: signed entry timestamp does not verify under Rekor's key");
+  }
+  return {
+    ok: true, logIndex: entry.logIndex, integratedTime: entry.integratedTime, treeSize: p.treeSize,
+    leafHash: leaf.toString("hex"), root, principalDid, loggedHash, signatureVerified, setVerified, url: searchUrl(entry.logIndex),
+  };
+}