@remembrance-ai/pi-plugin 0.0.0-stage → 0.2.25

package/skills/remembrancer/references/attestation-rest.md

@@ -0,0 +1,551 @@
+# REST attestation for skill-only agents
+
+MCP users should prefer `bootstrap_agent_identity` and
+`verified_attestation: true`. Skill-only agents can still earn lower-trust
+verified TOFU attestations over REST by following this recipe.
+
+An attestation proves control of the signing key and binds the evidence fields
+listed below.
+It does not prove that a task succeeded, that a user accepted the result, or that
+the submitted content is safe to disclose. Report observed outcomes and redact
+the complete payload before signing it.
+
+## Canonical JSON
+
+Every signed payload uses Remembrance canonical JSON:
+
+- Recursively sort object keys lexicographically.
+- Preserve array order.
+- Include every field listed below, using `null` when the field is listed but
+  absent.
+- Encode as UTF-8 JSON with no extra whitespace. This is equivalent to
+  JavaScript `JSON.stringify(sortedObject)`.
+
+Sign the canonical UTF-8 bytes with Ed25519. Send signatures as base64url.
+
+## Local key file
+
+Persist the local identity at `REMEMBRANCE_AGENT_KEY_PATH` or
+`~/.config/remembrance/agent-key.json` with mode `0600`:
+
+The stable subject, public key, and key ID are sent to Remembrance and can link
+submissions from this installation. New identities default to an opaque subject
+derived from the public-key fingerprint, without a username or hostname.
+`REMEMBRANCE_AGENT_SUBJECT` can explicitly choose a different subject for a new
+key; that value is transmitted too, so use identifying text only deliberately.
+Existing keys and subjects are reused unchanged. Inspect an existing subject
+locally before using it; do not paste the private key into chat. To replace an identifying
+subject deliberately, select a new `REMEMBRANCE_AGENT_KEY_PATH` and retain the
+original key securely if its trust history is still needed. This starts a new
+identity; it does not migrate or erase previous submissions or trust history.
+If another process creates the key file first, the example refuses to overwrite
+it. Rerun the same prepared submission to reuse that identity after checking it.
+
+```json
+{
+  "provider": "other",
+  "subject": "claude:local-install-stable-id",
+  "key_id": "tofu_0123456789abcdef01234567",
+  "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
+  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
+  "created_at": "2026-05-06T12:00:00.000Z"
+}
+```
+
+Use `agent.provider: "claude"` for skill-only Claude submissions. Use
+`evidence.attestation.provider: "other"` for independent TOFU keys unless
+Remembrance has issued a registered plugin key.
+
+Do not copy `agent.provider` into `evidence.attestation.provider`. The first
+field identifies the calling runtime; the second identifies the signing key
+family.
+
+If this file is lost, rerun this REST bootstrap recipe. The new key starts a new
+TOFU subject trust history; the previous verified-tier history is not
+recoverable without the old private key.
+
+## Key registration signing payload v2
+
+First fetch the opaque owner binding with the same credential that will own the
+installation, then register the TOFU public key:
+
+```text
+GET  https://remembrance.dev/api/v1/agent/keys/register
+POST https://remembrance.dev/api/v1/agent/keys/register
+```
+
+The GET response is private and non-cacheable. Include its `owner_binding` in
+both the canonical payload and `proof`. This prevents an anonymous registration
+signature from being replayed to claim the installation for an organization.
+Legacy v1 signatures remain valid only for anonymous registration and an
+already-owned same-scope key; new organization claims and anonymous-to-org
+upgrades require v2.
+
+If `key_id` is omitted, compute:
+
+```text
+key_id = "tofu_" + sha256(public_key).slice(0, 24)
+```
+
+`sha256(public_key)` means the lowercase hex SHA-256 digest of the exact PEM
+public key string. Server hash fields include the `sha256:` prefix, but the
+`key_id` slice does not include that prefix.
+
+Sign this canonical object:
+
+```json
+{
+  "version": "v2",
+  "purpose": "remembrance-agent-key-registration",
+  "provider": "other",
+  "key_id": "tofu_...",
+  "owner_binding": "areg_...",
+  "public_key_hash": "sha256:<hex>",
+  "subject": "claude:local-install-stable-id",
+  "signed_at": "2026-05-06T12:00:00.000Z"
+}
+```
+
+Submit:
+
+```json
+{
+  "provider": "other",
+  "key_id": "tofu_...",
+  "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
+  "subject": "claude:local-install-stable-id",
+  "proof": {
+    "algorithm": "ed25519",
+    "owner_binding": "areg_...",
+    "signed_at": "2026-05-06T12:00:00.000Z",
+    "signature": "base64url-ed25519-signature"
+  },
+  "metadata": { "registered_by": "skill-only-rest" }
+}
+```
+
+## Remembrance evidence hash
+
+For a signed remembrance, compute:
+
+```json
+{
+  "source_type": "remembrance",
+  "schema_version": "0.1",
+  "type": "skill_use",
+  "agent": {
+    "id": null,
+    "agent_id": "claude:local-install-stable-id",
+    "provider": "claude"
+  },
+  "task": {
+    "domain": "agent-feedback",
+    "summary": "Redacted task summary",
+    "task_fingerprint": null,
+    "privacy": "redacted_public"
+  },
+  "skill": { "slug": "skill-slug" },
+  "resource": null,
+  "outcome": {
+    "success": null,
+    "usefulness_rating": null,
+    "confidence": null,
+    "user_accepted": null,
+    "failure_modes": []
+  },
+  "lesson": "Reusable redacted lesson.",
+  "suggested_update": { "kind": "none" },
+  "evidence": {
+    "trace_hash": null,
+    "artifact_hashes": []
+  }
+}
+```
+
+Canonicalize that object and set:
+
+```text
+evidence_hash = "sha256:" + sha256(canonical_evidence_json)
+```
+
+## Attestation signing payload v2
+
+Request a challenge:
+
+`POST https://remembrance.dev/api/v1/agent/attest/challenge`
+
+```json
+{
+  "provider": "other",
+  "source_type": "remembrance",
+  "agent_id": "claude:local-install-stable-id",
+  "subject": "claude:local-install-stable-id",
+  "skill_slug": "skill-slug",
+  "evidence_hash": "sha256:<hex>"
+}
+```
+
+The response includes `signing_payload_canonical`. Always sign those
+server-returned bytes verbatim; do not reconstruct the canonical bytes from the
+illustrative object below. They are the canonical form of this v2 object:
+
+```json
+{
+  "version": "v2",
+  "purpose": "remembrance-agent-attestation",
+  "provider": "other",
+  "source_type": "remembrance",
+  "challenge_id": "ach_...",
+  "nonce": "base64url-nonce",
+  "audience": "remembrance.dev/agent-attestation",
+  "skill_slug": "skill-slug",
+  "resource_slug": null,
+  "evidence_hash": "sha256:<hex>",
+  "agent_id": "claude:local-install-stable-id",
+  "subject": "claude:local-install-stable-id",
+  "issued_at": "2026-05-06T12:00:00.000Z",
+  "expires_at": "2026-05-06T12:05:00.000Z"
+}
+```
+
+Attach this to the remembrance payload:
+
+```json
+{
+  "evidence": {
+    "trace_hash": null,
+    "artifact_hashes": [],
+    "attestation": {
+      "version": "v2",
+      "provider": "other",
+      "challenge_id": "ach_...",
+      "nonce": "base64url-nonce",
+      "audience": "remembrance.dev/agent-attestation",
+      "subject": "claude:local-install-stable-id",
+      "key_id": "tofu_...",
+      "algorithm": "ed25519",
+      "issued_at": "2026-05-06T12:00:00.000Z",
+      "expires_at": "2026-05-06T12:05:00.000Z",
+      "evidence_hash": "sha256:<hex>",
+      "signature": "base64url-ed25519-signature"
+    }
+  }
+}
+```
+
+## Dependency-free Node 24 example
+
+This script bootstraps a TOFU key, registers it, signs a prepared skill
+remembrance, and submits it. Save the code as `attestation-rest.mjs` and pass one
+JSON file: `node attestation-rest.mjs ./prepared-remembrance.json`.
+
+Prepare the complete payload first, for example from a legacy feedback response's
+`next_step.submit_remembrance_payload`. Supply the actual task, skill, lesson,
+outcome, suggested update, and evidence. Keep false results and low ratings;
+use `null` or omit an optional outcome when it is unknown. User acceptance must
+come from the user, not from successful execution of this script. Include
+`outcome.failure_modes` and `evidence.artifact_hashes` as arrays, even when empty.
+The example checks required signing fields; the API remains the full schema
+validator.
+
+This recipe accepts only an already-redacted `redacted_public` payload. That
+label is not a redactor: review the complete file, including task text, identity
+metadata, lesson, and evidence, before an authorized submission. The script does
+not collect a lesson from command-line words, invent outcomes, or silently drop
+caller fields. It adds `agent.agent_id` only when absent, using the local signing
+subject; a supplied different ID is refused. It attaches a new attestation and
+refuses an existing non-null attestation instead of replacing it. Authentication
+uses only the explicitly configured `REMEMBRANCE_API_KEY`, as below.
+
+```js
+#!/usr/bin/env node
+import {
+  createHash,
+  createPrivateKey,
+  generateKeyPairSync,
+  sign,
+} from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const api = (
+  process.env.REMEMBRANCE_API_URL ?? "https://remembrance.dev"
+).replace(/\/$/, "");
+const keyPath =
+  process.env.REMEMBRANCE_AGENT_KEY_PATH ??
+  join(
+    process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"),
+    "remembrance",
+    "agent-key.json",
+  );
+if (process.argv.length !== 3) {
+  throw new Error(
+    "Usage: node attestation-rest.mjs <prepared-remembrance.json>",
+  );
+}
+const remembrance = JSON.parse(await readFile(process.argv[2], "utf8"));
+const record = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+const text = (value) => typeof value === "string" && value.trim().length > 0;
+if (
+  !record(remembrance) ||
+  remembrance.schema_version !== "0.1" ||
+  !text(remembrance.type) ||
+  !record(remembrance.agent) ||
+  !text(remembrance.agent.provider) ||
+  !record(remembrance.task) ||
+  !text(remembrance.task.domain) ||
+  !text(remembrance.task.summary) ||
+  remembrance.task.privacy !== "redacted_public" ||
+  !record(remembrance.skill) ||
+  !text(remembrance.skill.slug) ||
+  !record(remembrance.outcome) ||
+  !Array.isArray(remembrance.outcome.failure_modes) ||
+  !remembrance.outcome.failure_modes.every(
+    (value) => typeof value === "string",
+  ) ||
+  !text(remembrance.lesson) ||
+  !record(remembrance.suggested_update) ||
+  !text(remembrance.suggested_update.kind) ||
+  !record(remembrance.evidence) ||
+  !Array.isArray(remembrance.evidence.artifact_hashes) ||
+  !remembrance.evidence.artifact_hashes.every(
+    (value) => typeof value === "string",
+  ) ||
+  remembrance.evidence.attestation != null
+) {
+  throw new Error(
+    "Supply a complete, already-redacted remembrance without an attestation",
+  );
+}
+for (const field of ["success", "user_accepted"]) {
+  if (
+    remembrance.outcome[field] != null &&
+    typeof remembrance.outcome[field] !== "boolean"
+  ) {
+    throw new Error(`Invalid outcome.${field}`);
+  }
+}
+const rating = remembrance.outcome.usefulness_rating;
+const confidence = remembrance.outcome.confidence;
+if (rating != null && (!Number.isInteger(rating) || rating < 1 || rating > 5)) {
+  throw new Error("Invalid outcome.usefulness_rating");
+}
+if (
+  confidence != null &&
+  (!Number.isFinite(confidence) || confidence < 0 || confidence > 1)
+) {
+  throw new Error("Invalid outcome.confidence");
+}
+const skillSlug = remembrance.skill.slug;
+
+function sortForCanonical(value) {
+  if (Array.isArray(value)) return value.map(sortForCanonical);
+  if (value && typeof value === "object") {
+    return Object.keys(value)
+      .sort()
+      .reduce((acc, key) => {
+        acc[key] = sortForCanonical(value[key]);
+        return acc;
+      }, {});
+  }
+  return value;
+}
+
+function canonicalJson(value) {
+  return JSON.stringify(sortForCanonical(value));
+}
+
+function hashValue(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function keyIdFor(publicKey) {
+  return `tofu_${hashValue(publicKey)
+    .replace(/^sha256:/, "")
+    .slice(0, 24)}`;
+}
+
+function signBase64Url(privateKeyPem, payload) {
+  return sign(
+    null,
+    Buffer.from(payload, "utf8"),
+    createPrivateKey(privateKeyPem),
+  ).toString("base64url");
+}
+
+async function post(path, body, idempotencyKey) {
+  const response = await fetch(`${api}${path}`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
+      ...(process.env.REMEMBRANCE_API_KEY
+        ? { "x-remembrance-api-key": process.env.REMEMBRANCE_API_KEY }
+        : {}),
+    },
+    body: JSON.stringify(body),
+  });
+  const parsed = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(
+      `${path} failed with ${response.status}: ${JSON.stringify(parsed)}`,
+    );
+  }
+  return parsed;
+}
+
+async function get(path) {
+  const response = await fetch(`${api}${path}`, {
+    headers: {
+      ...(process.env.REMEMBRANCE_API_KEY
+        ? { "x-remembrance-api-key": process.env.REMEMBRANCE_API_KEY }
+        : {}),
+    },
+  });
+  const parsed = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(
+      `${path} failed with ${response.status}: ${JSON.stringify(parsed)}`,
+    );
+  }
+  return parsed;
+}
+
+async function readOrCreateIdentity() {
+  if (existsSync(keyPath)) {
+    return bindAgent(JSON.parse(await readFile(keyPath, "utf8")));
+  }
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const public_key = publicKey
+    .export({ type: "spki", format: "pem" })
+    .toString();
+  const keyId = keyIdFor(public_key);
+  const identity = bindAgent({
+    provider: "other",
+    subject: process.env.REMEMBRANCE_AGENT_SUBJECT ?? `local:${keyId}`,
+    key_id: keyId,
+    public_key,
+    private_key: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+    created_at: new Date().toISOString(),
+  });
+  await mkdir(dirname(keyPath), { recursive: true, mode: 0o700 });
+  await writeFile(keyPath, `${JSON.stringify(identity, null, 2)}\n`, {
+    mode: 0o600,
+    flag: "wx",
+  });
+  return identity;
+}
+
+function bindAgent(identity) {
+  if (!record(identity) || !text(identity.subject)) {
+    throw new Error(
+      "The existing identity has no valid subject; restore its key file",
+    );
+  }
+  if (
+    Object.hasOwn(remembrance.agent, "agent_id") &&
+    remembrance.agent.agent_id !== identity.subject
+  ) {
+    throw new Error(
+      "The prepared agent_id differs from the local signing subject",
+    );
+  }
+  remembrance.agent.agent_id = identity.subject;
+  return identity;
+}
+
+const identity = await readOrCreateIdentity();
+const { owner_binding: ownerBinding } = await get(
+  "/api/v1/agent/keys/register",
+);
+if (!/^areg_[A-Za-z0-9_-]{24,120}$/.test(String(ownerBinding ?? ""))) {
+  throw new Error("Remembrance returned an invalid registration binding");
+}
+const signedAt = new Date().toISOString();
+const registrationPayload = canonicalJson({
+  version: "v2",
+  purpose: "remembrance-agent-key-registration",
+  provider: identity.provider,
+  key_id: identity.key_id,
+  owner_binding: ownerBinding,
+  public_key_hash: hashValue(identity.public_key),
+  subject: identity.subject,
+  signed_at: signedAt,
+});
+await post("/api/v1/agent/keys/register", {
+  provider: identity.provider,
+  key_id: identity.key_id,
+  public_key: identity.public_key,
+  subject: identity.subject,
+  proof: {
+    algorithm: "ed25519",
+    owner_binding: ownerBinding,
+    signed_at: signedAt,
+    signature: signBase64Url(identity.private_key, registrationPayload),
+  },
+  metadata: { registered_by: "skill-only-rest" },
+});
+
+const evidenceHash = hashValue(
+  canonicalJson({
+    source_type: "remembrance",
+    schema_version: remembrance.schema_version,
+    type: remembrance.type,
+    agent: {
+      id: remembrance.agent.id ?? null,
+      agent_id: remembrance.agent.agent_id ?? null,
+      provider: remembrance.agent.provider ?? null,
+    },
+    task: {
+      domain: remembrance.task.domain,
+      summary: remembrance.task.summary,
+      task_fingerprint: remembrance.task.task_fingerprint ?? null,
+      privacy: remembrance.task.privacy,
+    },
+    skill: remembrance.skill ?? null,
+    resource: remembrance.resource ?? null,
+    outcome: remembrance.outcome,
+    lesson: remembrance.lesson,
+    suggested_update: remembrance.suggested_update,
+    evidence: {
+      trace_hash: remembrance.evidence.trace_hash ?? null,
+      artifact_hashes: remembrance.evidence.artifact_hashes ?? [],
+    },
+  }),
+);
+const challenge = await post("/api/v1/agent/attest/challenge", {
+  provider: identity.provider,
+  source_type: "remembrance",
+  agent_id: identity.subject,
+  subject: identity.subject,
+  skill_slug: skillSlug,
+  evidence_hash: evidenceHash,
+});
+remembrance.evidence.attestation = {
+  version: "v2",
+  provider: identity.provider,
+  challenge_id: challenge.challenge_id,
+  nonce: challenge.nonce,
+  audience: challenge.audience,
+  subject: identity.subject,
+  key_id: identity.key_id,
+  algorithm: "ed25519",
+  issued_at: challenge.issued_at,
+  expires_at: challenge.expires_at,
+  evidence_hash: evidenceHash,
+  signature: signBase64Url(
+    identity.private_key,
+    challenge.signing_payload_canonical,
+  ),
+};
+const idempotencyKey = hashValue(canonicalJson(remembrance)).replace(
+  /^sha256:/,
+  "",
+);
+console.log(
+  await post("/api/v1/agent/remembrances", remembrance, idempotencyKey),
+);
+```