@passioncode-ai/fabric-agent-adapter 0.79.1 → 0.81.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/key-delivery-door/door.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+// A key-delivery door template (FAA-238), the twin of door.py: the same flags, the same exit codes, the same one line
+// on stdout. Read door.py's docstring for the rules. Node 20+, no dependency.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+
+export const ENVELOPE = 'fabric-credential-envelope/1';
+const MAX_ANSWER = 65536;
+const RETRIES = 2;
+const TRANSPORT_EXIT = 75;
+const TIME = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?Z$/;
+const B64URL = /^[A-Za-z0-9_-]+$/;
+const SIG = /^[A-Za-z0-9_-]{86}$/;
+const KEM = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,127}#kem$/;
+const SIGNER = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,127}(?:#sig)?$/;
+const CONTEXT = /^(?:personal|org:[A-Za-z0-9][A-Za-z0-9_-]{0,127})$/;
+const AGENT_REF = /^urn:fabric:agent:[a-z][a-z0-9]*(?:-[a-z0-9]+)*:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const SLOT = /^[A-Z][A-Z0-9_]{0,63}$/;
+const SLUG = /^[a-z][a-z0-9-]{1,62}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const REQUIRED = ['type', 'alg', 'suite', 'recipient', 'signer', 'context', 'agentRef', 'slot', 'provider', 'sequence', 'iat', 'exp', 'enc'];
+const ORG_ONLY = ['requestId', 'credentialExpiresAt'];
+
+export class Refusal extends Error {
+  constructor(code, message) { super(message); this.code = code; }
+}
+class Transport extends Error {}
+
+const when = (t) => Date.parse(t) / 1000;
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const str = (v, re) => typeof v === 'string' && re.test(v);
+
+export function envelopeProblems(envelope, want) {
+  if (!isObject(envelope) || Object.keys(envelope).sort().join() !== 'ct,header,sig') return ['not {header, ct, sig}'];
+  const h = envelope.header;
+  if (!isObject(h)) return ['header is not an object'];
+  let out = REQUIRED.filter((k) => !(k in h)).map((k) => `header misses ${k}`);
+  out = out.concat(Object.keys(h).filter((k) => !REQUIRED.includes(k) && !ORG_ONLY.includes(k)).sort().map((k) => `header has no member ${k}`));
+  if (out.length) return out;
+  const checks = [['type', h.type === ENVELOPE], ['suite', JSON.stringify(h.suite) === '[16,1,1]'],
+    ['recipient', str(h.recipient, KEM)], ['signer', str(h.signer, SIGNER)], ['context', str(h.context, CONTEXT)],
+    ['agentRef', str(h.agentRef, AGENT_REF) && h.agentRef.length <= 146], ['slot', str(h.slot, SLOT)],
+    ['provider', str(h.provider, SLUG)], ['sequence', Number.isInteger(h.sequence) && h.sequence >= 1 && h.sequence <= 9007199254740991],
+    ['iat', str(h.iat, TIME)], ['exp', str(h.exp, TIME)], ['enc', str(h.enc, B64URL)],
+    ['ct', str(envelope.ct, B64URL)], ['sig', str(envelope.sig, SIG)]];
+  out = checks.filter(([, ok]) => !ok).map(([name]) => `${name} does not read`);
+  if (out.length) return out;
+  const org = h.context !== 'personal';
+  if (h.alg !== (org ? 'EdDSA' : 'ES256')) out.push("alg is EdDSA in an organization's context, ES256 in the personal one");
+  if (org && !ORG_ONLY.every((k) => k in h)) out.push("an organization's envelope names requestId and credentialExpiresAt");
+  if (!org && ORG_ONLY.some((k) => k in h)) out.push('a personal envelope names no requestId or credentialExpiresAt');
+  if (org && 'requestId' in h && !str(h.requestId, UUID)) out.push('requestId does not read');
+  const iat = when(h.iat);
+  const exp = when(h.exp);
+  if (!(exp - iat > 0 && exp - iat <= 24 * 3600)) out.push('exp is after iat and at most 24 hours later');
+  if (org && 'credentialExpiresAt' in h) {
+    const end = h.credentialExpiresAt;
+    if (!(str(end, TIME) && iat < when(end) && when(end) <= iat + 30 * 86400)) out.push('credentialExpiresAt is after iat and at most 30 days later');
+  }
+  for (const key of ['recipient', 'context', 'agentRef', 'slot', 'provider', 'requestId']) {
+    if (key in want && h[key] !== want[key]) out.push(`header ${key} is not the one asked for`);
+  }
+  return out;
+}
+
+export const scrub = (text, value) => (value ? text.split(value).join('[value hidden]') : text);
+
+function runChild(argv, payload, timeoutS) {
+  const done = spawnSync(argv[0], argv.slice(1), { input: payload, timeout: timeoutS * 1000, maxBuffer: 4 * MAX_ANSWER });
+  if (done.error?.code === 'ETIMEDOUT') throw new Transport(`${argv[0]} did not answer in ${timeoutS} s`);
+  if (done.error?.code === 'ENOBUFS') return [done.status ?? 1, Buffer.alloc(0)];
+  if (done.error) throw new Refusal(2, `${argv[0]} cannot be run: ${done.error.code ?? done.error.message}`);
+  if (done.stdout.length > MAX_ANSWER) return [done.status, Buffer.alloc(0)];
+  return [done.status, done.stdout];
+}
+
+function parse(buf, code, message) {
+  try { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(buf)); } catch { throw new Refusal(code, message); }
+}
+
+export const commandIssuer = (argv, timeoutS) => (request) => {
+  const [code, out] = runChild(argv, JSON.stringify(request), timeoutS);
+  if (code === TRANSPORT_EXIT) throw new Transport('the issuer could not be reached');
+  if (code !== 0) throw new Refusal(3, `the issuer refused (exit ${code})`);
+  return parse(out, 4, "the issuer's answer is not JSON");
+};
+
+export const commandSealer = (argv, timeoutS) => (value, header) => {
+  let code; let out;
+  try { [code, out] = runChild(argv, JSON.stringify({ value, header }), timeoutS); } catch (err) {
+    if (err instanceof Transport) throw new Refusal(5, 'the sealer did not answer');
+    throw err;
+  }
+  if (code !== 0) throw new Refusal(5, `the sealer refused (exit ${code})`);
+  return parse(out, 5, "the sealer's answer is not JSON");
+};
+
+export function deliver(want, issue, seal, { sleep = (s) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, s * 1000) } = {}) {
+  const request = {};
+  for (const k of ['slot', 'provider', 'agentRef', 'context', 'requestId']) if (k in want) request[k] = want[k];
+  let answer;
+  for (let attempt = 0; ; attempt += 1) {
+    try { answer = issue(request); break; } catch (err) {
+      if (!(err instanceof Transport)) throw err;
+      if (attempt === RETRIES) throw new Refusal(1, `transport failure after ${RETRIES + 1} tries: ${err.message}`);
+      sleep(attempt + 1);
+    }
+  }
+  if (isObject(answer) && isObject(answer.refused)) {
+    const code = answer.refused.code;
+    throw new Refusal(3, `the issuer refused: ${str(code, SLUG) ? code : 'no code'}`);
+  }
+  const value = isObject(answer) ? answer.value : undefined;
+  if (typeof value !== 'string' || !value.trim() || /[\r\n]/.test(value)) throw new Refusal(4, "the issuer's answer holds no key");
+  const header = { type: ENVELOPE, recipient: want.recipient, context: want.context, agentRef: want.agentRef, slot: want.slot, provider: want.provider };
+  if (want.context !== 'personal') {
+    header.requestId = want.requestId;
+    if (typeof answer.credentialExpiresAt === 'string') header.credentialExpiresAt = answer.credentialExpiresAt;
+  }
+  const envelope = seal(value, header);
+  let problems = envelopeProblems(envelope, want);
+  const line = JSON.stringify(envelope);
+  if (!problems.length && line.includes(value)) problems = ['the envelope carries the value in clear'];
+  if (problems.length) throw new Refusal(5, `the sealed envelope is refused: ${problems.map((p) => scrub(p, value)).join('; ')}`);
+  return line;
+}
+
+function split(command) { // shlex.split's POSIX subset: quotes and backslashes
+  const out = []; let cur = ''; let quote = null; let any = false;
+  for (let i = 0; i < command.length; i += 1) {
+    const c = command[i];
+    if (quote === "'") { if (c === "'") quote = null; else cur += c; continue; }
+    if (quote === '"') { if (c === '"') quote = null; else if (c === '\\' && i + 1 < command.length && '"\\$`'.includes(command[i + 1])) cur += command[++i]; else cur += c; continue; }
+    if (c === "'" || c === '"') { quote = c; any = true; } else if (c === '\\' && i + 1 < command.length) { cur += command[++i]; any = true; } else if (/\s/.test(c)) { if (any) out.push(cur); cur = ''; any = false; } else { cur += c; any = true; }
+  }
+  if (quote) throw new Error('No closing quotation');
+  if (any) out.push(cur);
+  return out;
+}
+
+export function main(argv) {
+  let v;
+  try {
+    v = parseArgs({ args: argv, strict: true, options: Object.fromEntries(['slot', 'provider', 'agent-ref', 'recipient', 'context',
+      'issuer-command', 'seal-command', 'request-id', 'timeout'].map((k) => [k, { type: 'string' }])) }).values;
+  } catch (err) {
+    process.stderr.write(`door.mjs: usage: ${err.message}\n`);
+    return 2;
+  }
+  const usage = [];
+  for (const k of ['slot', 'provider', 'agent-ref', 'recipient', 'context', 'issuer-command', 'seal-command']) if (v[k] === undefined) usage.push(`--${k} is required`);
+  if (usage.length) { process.stderr.write(`door.mjs: usage: ${usage.join(', ')}\n`); return 2; }
+  const want = { slot: v.slot, provider: v.provider, agentRef: v['agent-ref'], recipient: v.recipient, context: v.context };
+  for (const [name, re, value] of [['--slot', SLOT, v.slot], ['--provider', SLUG, v.provider], ['--agent-ref', AGENT_REF, v['agent-ref']],
+    ['--recipient', KEM, v.recipient], ['--context', CONTEXT, v.context]]) if (!re.test(value)) usage.push(name);
+  if (v.context !== 'personal') {
+    if (!str(v['request-id'], UUID)) usage.push("--request-id (an organization's context answers a credential-request/1)");
+    want.requestId = v['request-id'];
+  } else if (v['request-id']) usage.push('--request-id (a personal envelope names none)');
+  const timeout = v.timeout === undefined ? 60 : Number(v.timeout);
+  if (!(timeout > 0)) usage.push('--timeout');
+  let issuer = []; let sealer = [];
+  try { issuer = split(v['issuer-command']); sealer = split(v['seal-command']); } catch (err) { usage.push(`a command that does not split: ${err.message}`); }
+  if (usage.length || !issuer.length || !sealer.length) {
+    process.stderr.write(`door.mjs: usage: ${(usage.length ? usage : ['an empty command']).join(', ')}\n`);
+    return 2;
+  }
+  try {
+    process.stdout.write(`${deliver(want, commandIssuer(issuer, timeout), commandSealer(sealer, timeout))}\n`);
+    return 0;
+  } catch (err) {
+    if (!(err instanceof Refusal)) throw err;
+    process.stderr.write(`door.mjs: ${err.message}\n`);
+    return err.code;
+  }
+}
+
+const invoked = (() => { try { return fs.realpathSync(process.argv[1] ?? ''); } catch { return null; } })();
+if (invoked === fileURLToPath(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/key-delivery-door/door.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""A key-delivery door template (FAA-238): ask an issuer for one key, print it sealed as the DEC-0111 envelope.
+
+  python3 door.py --slot NAME --provider SLUG --agent-ref URN --recipient KID#kem --context personal|org:<id>
+                  [--request-id UUID] --issuer-command "CMD ..." --seal-command "CMD ..." [--timeout 60]
+
+The door prints exactly one `fabric-credential-envelope/1` (contract DEC-0111) on stdout and writes into no store: the
+receiver puts it in the recipient's slot (Project Observatory's `vault.py receive PROJECT ENV NAME --from-command --
+door.py ...`, its V2 spec, until its OBS-360 ships). The value is never in argv, the environment, a file or stderr.
+
+The two commands are the door owner's (a value travels only over their stdin and stdout, held in memory):
+- the issuer command reads the request (`{slot, provider, agentRef, context, requestId?}`, no secret) on stdin and
+  prints `{"value": "<key>", "credentialExpiresAt"?: "<RFC 3339>"}` or `{"refused": {"code": "<code>"}}`; exit 75
+  (EX_TEMPFAIL) is a transport failure, any other non-zero exit a refusal;
+- the seal command reads `{"value", "header"}` on stdin (the header's fields the door fixes) and prints the envelope,
+  sealed with HPKE and signed as DEC-0111 says (the contract's `sealCredential`); the standard library seals nothing.
+
+Exit codes, as Observatory's `receive --from-command` maps them: 0 delivered (the envelope on stdout), 2 usage,
+3 the issuer refused, 4 no key in the issuer's answer, 5 the store refused (the envelope cannot be sealed for the
+recipient's store: the sealer refused, or its envelope fails the checks below), 1 a transport failure that outlived
+its retries. Only a transport failure is retried, at most twice.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import re
+import shlex
+import subprocess
+import sys
+import time
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
+
+ENVELOPE = "fabric-credential-envelope/1"
+MAX_ANSWER = 65536
+RETRIES = 2
+TRANSPORT_EXIT = 75
+_TIME = re.compile(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?Z\Z")
+_B64URL = re.compile(r"^[A-Za-z0-9_-]+\Z")
+_SIG = re.compile(r"^[A-Za-z0-9_-]{86}\Z")
+_KEM = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:~-]{0,127}#kem\Z")
+_SIGNER = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:~-]{0,127}(?:#sig)?\Z")
+_CONTEXT = re.compile(r"^(?:personal|org:[A-Za-z0-9][A-Za-z0-9_-]{0,127})\Z")
+_AGENT_REF = re.compile(r"^urn:fabric:agent:[a-z][a-z0-9]*(?:-[a-z0-9]+)*:[a-z][a-z0-9]*(?:-[a-z0-9]+)*\Z")
+_SLOT = re.compile(r"^[A-Z][A-Z0-9_]{0,63}\Z")
+_SLUG = re.compile(r"^[a-z][a-z0-9-]{1,62}\Z")
+_UUID = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\Z")
+_REQUIRED = ("type", "alg", "suite", "recipient", "signer", "context", "agentRef", "slot", "provider", "sequence",
+             "iat", "exp", "enc")
+_ORG_ONLY = ("requestId", "credentialExpiresAt")
+
+
+class Refusal(Exception):
+    """An exit the door answers with: code and a message that never holds the value."""
+
+    def __init__(self, code: int, message: str):
+        super().__init__(message)
+        self.code = code
+
+
+class Transport(Exception):
+    """The issuer could not be reached: the one failure worth another try."""
+
+
+def _when(text: str) -> float:
+    return _dt.datetime.fromisoformat(text.replace("Z", "+00:00")).timestamp()
+
+
+def envelope_problems(envelope: Any, want: Dict[str, Any]) -> List[str]:
+    """What keeps an envelope from the DEC-0111 shape (credential-envelope.schema.json at the adapter's pin) and from the
+    request it answers. Never decrypts or verifies a signature: that is the target's checkCredentialEnvelope."""
+    if not isinstance(envelope, dict) or set(envelope) != {"header", "ct", "sig"}:
+        return ["not {header, ct, sig}"]
+    h, out = envelope["header"], []
+    if not isinstance(h, dict):
+        return ["header is not an object"]
+    out += ["header misses %s" % k for k in _REQUIRED if k not in h]
+    out += ["header has no member %s" % k for k in sorted(set(h) - set(_REQUIRED) - set(_ORG_ONLY))]
+    if out:
+        return out
+    checks = [("type", h["type"] == ENVELOPE), ("suite", h["suite"] == [16, 1, 1]),
+              ("recipient", isinstance(h["recipient"], str) and bool(_KEM.match(h["recipient"]))),
+              ("signer", isinstance(h["signer"], str) and bool(_SIGNER.match(h["signer"]))),
+              ("context", isinstance(h["context"], str) and bool(_CONTEXT.match(h["context"]))),
+              ("agentRef", isinstance(h["agentRef"], str) and len(h["agentRef"]) <= 146 and bool(_AGENT_REF.match(h["agentRef"]))),
+              ("slot", isinstance(h["slot"], str) and bool(_SLOT.match(h["slot"]))),
+              ("provider", isinstance(h["provider"], str) and bool(_SLUG.match(h["provider"]))),
+              ("sequence", type(h["sequence"]) is int and 1 <= h["sequence"] <= 9007199254740991),
+              ("iat", isinstance(h["iat"], str) and bool(_TIME.match(h["iat"]))),
+              ("exp", isinstance(h["exp"], str) and bool(_TIME.match(h["exp"]))),
+              ("enc", isinstance(h["enc"], str) and bool(_B64URL.match(h["enc"]))),
+              ("ct", isinstance(envelope["ct"], str) and bool(_B64URL.match(envelope["ct"]))),
+              ("sig", isinstance(envelope["sig"], str) and bool(_SIG.match(envelope["sig"])))]
+    out += ["%s does not read" % name for name, ok in checks if not ok]
+    if out:
+        return out
+    org = h["context"] != "personal"
+    if h["alg"] != ("EdDSA" if org else "ES256"):
+        out.append("alg is EdDSA in an organization's context, ES256 in the personal one")
+    if org and not all(k in h for k in _ORG_ONLY):
+        out.append("an organization's envelope names requestId and credentialExpiresAt")
+    if not org and any(k in h for k in _ORG_ONLY):
+        out.append("a personal envelope names no requestId or credentialExpiresAt")
+    if org and "requestId" in h and not (isinstance(h["requestId"], str) and _UUID.match(h["requestId"])):
+        out.append("requestId does not read")
+    iat, exp = _when(h["iat"]), _when(h["exp"])
+    if not 0 < exp - iat <= 24 * 3600:
+        out.append("exp is after iat and at most 24 hours later")
+    if org and "credentialExpiresAt" in h:
+        end = h["credentialExpiresAt"]
+        if not (isinstance(end, str) and _TIME.match(end) and iat < _when(end) <= iat + 30 * 86400):
+            out.append("credentialExpiresAt is after iat and at most 30 days later")
+    for key in ("recipient", "context", "agentRef", "slot", "provider", "requestId"):
+        if key in want and h.get(key) != want[key]:
+            out.append("header %s is not the one asked for" % key)
+    return out
+
+
+def scrub(text: str, value: Optional[str]) -> str:
+    return text.replace(value, "[value hidden]") if value else text
+
+
+def run_child(argv: Sequence[str], payload: bytes, timeout: float) -> Tuple[int, bytes, str]:
+    """A child with the payload on stdin; its stdout in memory (at most 64 KiB), its stderr as text."""
+    try:
+        done = subprocess.run(list(argv), input=payload, capture_output=True, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        raise Transport("%s did not answer in %g s" % (argv[0], timeout))
+    except OSError as exc:
+        raise Refusal(2, "%s cannot be run: %s" % (argv[0], exc.strerror or exc))
+    if len(done.stdout) > MAX_ANSWER:
+        return done.returncode, b"", "its answer is over %d bytes" % MAX_ANSWER
+    return done.returncode, done.stdout, done.stderr.decode("utf-8", "replace")
+
+
+def command_issuer(argv: Sequence[str], timeout: float) -> Callable[[Dict[str, Any]], Dict[str, Any]]:
+    def issue(request: Dict[str, Any]) -> Dict[str, Any]:
+        code, out, err = run_child(argv, json.dumps(request).encode(), timeout)
+        if code == TRANSPORT_EXIT:
+            raise Transport("the issuer could not be reached")
+        if code != 0:
+            raise Refusal(3, "the issuer refused (exit %d)" % code)
+        try:
+            return json.loads(out.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            raise Refusal(4, "the issuer's answer is not JSON")
+    return issue
+
+
+def command_sealer(argv: Sequence[str], timeout: float) -> Callable[[str, Dict[str, Any]], Any]:
+    def seal(value: str, header: Dict[str, Any]) -> Any:
+        try:
+            code, out, _err = run_child(argv, json.dumps({"value": value, "header": header}).encode(), timeout)
+        except Transport:
+            raise Refusal(5, "the sealer did not answer")
+        if code != 0:
+            raise Refusal(5, "the sealer refused (exit %d)" % code)
+        try:
+            return json.loads(out.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            raise Refusal(5, "the sealer's answer is not JSON")
+    return seal
+
+
+def deliver(want: Dict[str, Any], issue: Callable[[Dict[str, Any]], Dict[str, Any]],
+            seal: Callable[[str, Dict[str, Any]], Any], *, sleep: Callable[[float], None] = time.sleep) -> str:
+    """The envelope's one line, or a Refusal. `want` names slot, provider, agentRef, recipient, context, requestId?."""
+    request = {k: want[k] for k in ("slot", "provider", "agentRef", "context", "requestId") if k in want}
+    for attempt in range(RETRIES + 1):
+        try:
+            answer = issue(request)
+            break
+        except Transport as exc:
+            if attempt == RETRIES:
+                raise Refusal(1, "transport failure after %d tries: %s" % (RETRIES + 1, exc))
+            sleep(1.0 * (attempt + 1))
+    if isinstance(answer, dict) and isinstance(answer.get("refused"), dict):
+        code = answer["refused"].get("code")
+        raise Refusal(3, "the issuer refused: %s" % (code if isinstance(code, str) and _SLUG.match(code) else "no code"))
+    value = answer.get("value") if isinstance(answer, dict) else None
+    if not isinstance(value, str) or not value.strip() or "\n" in value or "\r" in value:
+        raise Refusal(4, "the issuer's answer holds no key")
+    header = {"type": ENVELOPE, "recipient": want["recipient"], "context": want["context"], "agentRef": want["agentRef"],
+              "slot": want["slot"], "provider": want["provider"]}
+    if want["context"] != "personal":
+        header["requestId"] = want["requestId"]
+        if isinstance(answer.get("credentialExpiresAt"), str):
+            header["credentialExpiresAt"] = answer["credentialExpiresAt"]
+    envelope = seal(value, header)
+    problems = envelope_problems(envelope, want)
+    line = json.dumps(envelope, separators=(",", ":"))
+    if not problems and value in line:
+        problems = ["the envelope carries the value in clear"]
+    if problems:
+        raise Refusal(5, "the sealed envelope is refused: %s" % "; ".join(scrub(p, value) for p in problems))
+    return line
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    for flag in ("--slot", "--provider", "--agent-ref", "--recipient", "--context", "--issuer-command", "--seal-command"):
+        parser.add_argument(flag, required=True)
+    parser.add_argument("--request-id")
+    parser.add_argument("--timeout", type=float, default=60.0)
+    args = parser.parse_args(argv)
+    want = {"slot": args.slot, "provider": args.provider, "agentRef": args.agent_ref, "recipient": args.recipient,
+            "context": args.context}
+    usage = [name for name, pattern, value in (("--slot", _SLOT, args.slot), ("--provider", _SLUG, args.provider),
+                                               ("--agent-ref", _AGENT_REF, args.agent_ref), ("--recipient", _KEM, args.recipient),
+                                               ("--context", _CONTEXT, args.context)) if not pattern.match(value)]
+    if args.context != "personal":
+        if not (args.request_id and _UUID.match(args.request_id)):
+            usage.append("--request-id (an organization's context answers a credential-request/1)")
+        want["requestId"] = args.request_id
+    elif args.request_id:
+        usage.append("--request-id (a personal envelope names none)")
+    try:
+        issuer, sealer = shlex.split(args.issuer_command), shlex.split(args.seal_command)
+    except ValueError as exc:
+        usage.append("a command that does not split: %s" % exc)
+        issuer = sealer = []
+    if usage or not issuer or not sealer:
+        print("door.py: usage: %s" % ", ".join(usage or ["an empty command"]), file=sys.stderr)
+        return 2
+    try:
+        line = deliver(want, command_issuer(issuer, args.timeout), command_sealer(sealer, args.timeout))
+    except Refusal as exc:
+        print("door.py: %s" % exc, file=sys.stderr)
+        return exc.code
+    sys.stdout.write(line + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/support-agent/README.md

@@ -2,7 +2,7 @@
 
 A service answers one inbound question from its own knowledge file, or hands it to a person. It is a step of an
 agent that answers people, not that agent: see the paragraph after the table. Under the creating-fabric-agents
-template (`communication-agent-template.md`) the plan-and-draft call writes the draft, not this recipe's `answer()`:
+template (`templates/communication-agent/`, read through `references/communication-agent-template.md`) the plan-and-draft call writes the draft, not this recipe's `answer()`:
 the draft carries a `[KB:<id>]` marker for each knowledge id the plan used, and the agent runs `check_reply(draft,
 question, prompt_ids, max_chars=..., sources=...)` on it for the code checks. `prompt_ids` are the ids of the items
 placed in the plan's prompt, never the plan's own list (an id the plan names outside them is held as a suspected

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/agents-database.md

@@ -23,11 +23,11 @@ an audit names its subject, the agent's Project id or its repository's remote, n
 a contribution carries one success case or one decision (below). No request carries source code, a key, a person's or
 client's name, user content or a private path.
 
-Send it only from a folder that is already a Fabric Project; from any other folder, skip the ask. Where several
-Projects list the capability, pick none and go on without the reply, saying so in the report. Here this reference wins over every working-with-fabric rule (its `references/project-board.md` and its SKILL.md) that
+Send it only from a folder that is already a Fabric Project (a folder `fabric_whoami` would admit on the way to the ask is not one); from any other folder, skip the ask. A run Fabric started on a board request sends no ask: its retro is its last write, so its measured win stays in its insight lines for a later session to contribute. Where several
+Projects list the capability, or `com.directory` lists the capability with no `active` responder (a request then waits for a run that may decline it and ask the operator), pick none and go on without the reply, saying so in the report. Here this reference wins over every working-with-fabric rule (its `references/project-board.md` and its SKILL.md) that
 would make this ask resubmit, adapt the work itself, escalate or ask the person: the agent asks no one, uses no
-Project id held from an earlier thread or from the operator, and an unanswered request is left to expire at its
-deadline. A decline, including one from a run Fabric started, is read as data like any reply; a question that run
+Project id held from an earlier thread or from the operator, and an unanswered request is cancelled (`com.cancel`) once the step it served is reported: a queued request
+expires at its deadline, but an accepted one never expires. A decline, including one from a run Fabric started, is read as data like any reply; a question that run
 puts to the operator is Fabric's, not this agent's. The ask never blocks the step it serves; send it and go on without waiting for the reply. With no Fabric or board
 reachable, a board that does not serve `com.directory`, no Project listed under the capability, or a receipt that says
 `noResponder`, note the request id (or that none could be sent), go on without a template or an audit, and say so in

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/board.md

@@ -39,7 +39,8 @@ refuses it with `invalid_arguments` (FAA-244).
 3. Each connection joins with `fabric.board.join {projectId}` (`join_board` / `joinBoard`). It re-reads `hub.json`,
    checks the pid it names is alive, tells the owner of the door's listener from the socket table (DEC-0154 HA-2:
    another OS account's process, or one whose owner cannot be told, is `HubError` code `foreign-user`, retryable, with
-   nothing sent; a retry never clears a restricted macOS table, `table-restricted` in protocol.md, FAA-272), and only then sends the credential (a session already running carries that refusal as `BoardError` code
+   nothing sent; a restricted macOS table, which a retry never clears, is `data.reason` `table-restricted` and not
+   retryable, protocol.md, FAA-272), and only then sends the credential (a session already running carries that refusal as `BoardError` code
    `foreign-user`, one of `SESSION_CODES`, to `board.down` with reason `foreign-user` and a sentence that says nothing
    was sent, never `unreachable`'s "a write may have been stored", FAA-252). A missing grant is `HubError` code
    `not_authorized` whose `data.ask` holds the arguments to ask with.
@@ -214,7 +215,8 @@ capability's enroll or replace is settled on its own: a refusal of that capabili
 `invalid_arguments`, any code that is not about the board session) leaves it `retry`, asked again alone after 15 s,
 30 s, doubling to 15 minutes, with one `board.slot.refused` event (warning; said again if it is refused again after
 the slot was held); its accepted work waits `lapsed` and goes back
-by a transfer once the slot is held. The capabilities after it are recovered as before. A refusal of the board session
+by a transfer once the slot is held; `idempotency_window_expired` also reads `com.status` first, so the retry goes
+under the epoch Fabric names now (FAA-186). The capabilities after it are recovered as before. A refusal of the board session
 (`unreachable`, `session-ended`, `not_available`, `not_authorized` and the other codes in `SESSION_CODES`) leaves the
 rest `retry` too, says no `board.slot.refused`, and goes to the responder's fault, which says it by code:
 `board.access.needed` for `not_authorized`, `authority_changed` and `credential` (the session is left),

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/dashboard-links.md

@@ -28,7 +28,7 @@ other browser, unless Fabric Dashboards is confirmed not installed.
    is also authoritative. Hand back **the returned `open_link` as the primary
    dashboard action**. Do not rebuild its URI or double-encode `path`.
 3. Use `host_status`, where offered, to distinguish available, not_installed,
-   unknown, incompatible and handler_mismatch. It is a read, not a GUI launch.
+   unknown, incompatible, handler_mismatch and unsupported. It is a read, not a GUI launch.
    With an older server lacking that tool, host readiness is unverified: use a
    compatible host resolver or report the limitation, not presumed absence.
 4. A request for a link opens nothing. A request to open uses the host `open`
@@ -65,8 +65,8 @@ host's `open` with `fallback=never`. Never `open <url>`, `open -a Safari`,
 agent's pages. A browser only when `host_status` confirms `not_installed`, and
 a raw `http://127.0.0.1:<port>` address only after the listener on that port is
 this OS account's (DEC-0154 PL-3 and HA-2; the adapter's `building-fabric-services/scripts/fabric_peer_owner.py`: `server_end` of a connection it opens and sends nothing on; `check_service.py <id>.<instance>` prints it as `listener.owner`): a
-`foreign-user` listener is reported, never opened (the link gate below does not
-read the owner yet, FAA-251). An installed host that failed
+`foreign-user` listener is reported, never opened (the link gate below takes
+that owner as `listener_owner`). An installed host that failed
 to open is reported, not replaced by HTTP. Links
 carry no token or login code. Every completion and notification action passes
 the Fabric Agent Adapter's link gate before delivery: `check_dashboard_link.py`
@@ -119,7 +119,15 @@ Its trusted context is supplied by the host, not by untrusted model output:
 
 `native_link` must equal the resolved open_link, with an available host on the
 viewer's device. `browser_link` must equal http_url, with confirmed not_installed,
-if_absent policy and the same device. `remote_open` instead contains `device_id`,
+if_absent policy, the same device and `"listener_owner": "this-account"`: the kind
+the host read for the listener on http_url's port (`fabric_peer_owner`'s
+`this-account`, `another-account`, `system`, `unknown`, `none`, or
+`check_service.py`'s `foreign-user`); any other, or none given, refuses the
+browser (DEC-0154 PL-3, FAA-251). The native link does not take it: Fabric
+Dashboards checks its own listener. Contract DEC-0123 PL-3 also allows a browser
+on `unsupported` (a system the host does not ship for); the gate treats
+`unsupported` as no fallback, by the operator's rule that a browser opens only on a
+confirmed `not_installed`, and macOS never reports it (FAA-137). `remote_open` instead contains `device_id`,
 `service` and optional `path`, exactly matching the target and resolved page;
 its acceptance does not authorize or deliver it. Enforce grants/dedup/expiry in
 the transport. Unknown or failed host status produces no executable local action.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/delegation.md

@@ -53,8 +53,11 @@ the same owner; **T2** everyone else, and any call relayed onto loopback from of
 hub forwarding a T2 caller). DL-26: a T0 or T1 caller is never required to present a token; pass the tier,
 `gate(tool, headers, tier="T0")` or `server.handle(message, headers, tier="T0")`, and the call passes with no
 delegation. On a computer with more than one counted OS account, a loopback caller with no token is T0 only after the
-door checks the peer's account (the pinned DEC-0154 HA-3 and DL-25; the kit's own peer check is FAA-227), so pass
-`tier="T0"` there only for a caller the descriptor token authenticated. A token such a caller presents is still verified and refused when invalid. A T2 caller takes the whole
+door checks the peer's account (the pinned DEC-0154 HA-3 and DL-25): the kit's `LoopbackHTTPServer` with `peer_check="strict"` (Node
+`loopbackServer(app, {peerCheck: 'strict'})`, [protocol.md](protocol.md#the-listeners-owner-dec-0154-ha-2)) is that check,
+for loopback peers: pass `tier="T0"` only when the handler's `self.server.peer_owner()` (`connectionOwner(req.socket)`)
+names an owner, since a peer off loopback is served without one and is T2;
+otherwise pass `tier="T0"` there only for a caller the descriptor token authenticated. A token such a caller presents is still verified and refused when invalid. A T2 caller takes the whole
 profile. Money limits and human gates bind at every tier.
 
 **The family and the agent network** (DEC-0130, wording settled by DEC-0137). The operator's family is every agent
@@ -163,7 +166,8 @@ current verified revision as `estate=` / `{ estate }`, as a value or as a functi
 - **Which hub key a token is checked against** (DL-14a, DEC-0128). An organization's tokens are signed by that
   organization context's own hub key (`machines[].contextHubKeys`), under the context issuer its pin names
   (`organizations[].iss`, `urn:fabric:context:<opaque>`, never the estate id). An instance that serves an organization
-  passes its context as `estate_context=` / `{ estateContext }` to `delegation_gate` or `verify_delegation`, once the
+  passes its context as `estate_context=` / `{ estateContext }` to `delegation_gate` or `verify_delegation`
+  (`fabric_context.context_gate_options` hands it and the pin's `iss` back, FAA-150), once the
   record pins its organization (until then its tokens are refused `kid-not-certified`, brief D5), and that pin's `iss`
   as `issuer`: the `kid` is then trusted only when one machine lists it for that context with that key and
   the record pins the organization. Without it, or with `personal`, the personal `hubKey` is read, so a context key

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/estate-record.md

@@ -98,6 +98,15 @@ gate = fd.delegation_gate(audience=..., jwks=keys, issuer=pin["iss"], effects=..
                           estate_context="org:acme-rehearsal")     # the context fabric_context started it for
 ```
 
+`fabric_context.context_gate_options(info, record)` / `contextGateOptions(info, record)` hands both back from the
+instance `hold_context_instance` started (FAA-150): `estate_context` always, and `issuer` when the record pins that
+organization; spread it after the estate issuer, so a personal instance keeps the estate's:
+
+```python
+gate = fd.delegation_gate(audience=..., jwks=keys, effects=..., estate=lambda: current,
+                          **{"issuer": estate_issuer, **fabric_context.context_gate_options(info, current)})
+```
+
 The `kid` is then certified only when exactly one machine lists it for that context with the published key and the
 revision pins the organization; omitted or `personal`, the personal `hubKey` is read. A context key never verifies a
 personal token, the personal key never an organization's, and a context that is neither (`Org:x`, a trailing space, a
@@ -218,7 +227,9 @@ const { dirs, instance, lock } = await holdContextInstance('example-agent', 'org
   kept; another context or instance, or unreadable, releases the lock and refuses. The folder never changes context.
 
 A refusal is one sentence on stderr naming the code and the context, never a record or grant value, and exit 78
-(`EXIT_CONTEXT_REFUSED`, EX_CONFIG; 75 stays "already running"). `ContextRefused` carries the code:
+(`EXIT_CONTEXT_REFUSED`, EX_CONFIG; 75 stays "already running"); a copy its supervisor started waits the lock's
+back-off (300 s in all) before that exit, so `KeepAlive` does not restart it every 10 s (FAA-279). `ContextRefused`
+carries the code:
 
 | Code | When |
 |---|---|