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

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/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`
@@ -119,7 +119,10 @@ 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 and the same device. 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

@@ -163,7 +163,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 |
 |---|---|

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

@@ -125,6 +125,7 @@ action it also carries the operator's decision, [Actions](#actions)), act on eve
 (`jobs.quotaExhausted(id, message, {retryable, resetsAt})`, `jobCallerAction`, `intentIdempotencyKey`). The guidance
 for an agent's own design is in `creating-fabric-agents/references/resilience-and-autonomy.md`.
 
+<a id="a-nodes-call-queue"></a>
 **A node's call queue (DEC-0104).** A provider that queues refuses a start past its queue with `queue-full`: an `isError`
 result with one text item whose JSON is `{error: {code: "queue-full", message, data: {retryable, retryAfterSeconds}}}`,
 never `structuredContent`; the caller starts again after `retryAfterSeconds` under the same key. Read that refusal
@@ -132,9 +133,31 @@ from the start's own `isError` result, before any answer reaches `job_caller_act
 job, and `queue-full` never ends one, so they answer a job it ended `invalid` (`QUEUE_FULL` names the code, and the
 kit's job store refuses to end a job with it). The kit has no reader for the refusal yet (FAA-103). Through Fabric's hub
 a caller today sees `product-error` instead, kept under the key for 24 hours, until the hub relays `queue-full`
-(Fabric CO-376). The kit does not queue: it declares no load extension (`extensions/load/0.1`) and serves no
-`fabric.job.list`, so its `unknown-job` and repeated keys keep the rules above. A node that will queue needs
-`jobCallerKey`, the contract's `agent-network.json` vectors and the load report first (FAA-103).
+(Fabric CO-376). The kit's job store does not queue by itself: it declares no load extension (`extensions/load/0.1`)
+and serves no `fabric.job.list`, so its `unknown-job` and repeated keys keep the rules above.
+
+A node that queues takes the contract's reference functions from the kit instead of copying them (since 0.80.0,
+FAA-289): `fabric_load.py` and `fabric-load.mjs`, exported by both facades, held to the contract's
+`fixtures/vectors/agent-network.json` and its `job-queue`, `service-load` and `service-well-known-load` fixtures at the
+pin (vendored as `test/fixtures/contract/load-vectors.json` by `make_load_vectors.mjs`):
+
+| Python | Node | What |
+|---|---|---|
+| `job_caller_key(accepted, credential)` | `jobCallerKey` | the caller's opaque key: an accepted delegation's `principal`, `caller` and a partner organization ending the chain, else the credential; `None` / `undefined` for a refused or unreadable call |
+| `next_queued_job(queue, running, limits)` | `nextQueuedJob` | the id to start next per (agentRef, context): nothing at `concurrency`, a caller at `perCaller` waits, the caller running fewest first, then the oldest arrival, ties by id |
+| `admit_job(queue, running, job, limits, retry_after_seconds)` | `admitJob` | `{admit: True}` when the job would start at once or fewer than `queueMax` wait, else the `queue-full` error with `retryAfterSeconds` (1 to 3600, else 60) |
+| `queue_status_message(position, length)` | `queueStatusMessage` | a waiting job's `statusMessage`, `queued <position> of <length>` |
+| `read_queue_position(status_message)` | `readQueuePosition` | `{position, length}` from that message, or none |
+| `job_queue_rules(value)` | `jobQueueRules` | FAC-SEM-131 on `{queue, running, limits, started}` |
+| `load_report_rules(report)` | `loadReportRules` | FAC-SEM-132 on a `service-load/1` report: windows one `windowSeconds` apart, none after `generatedAt`, one row per context, p50 at most p95, a run time only where a job ended |
+| `load_report_problems(report)` | `loadReportProblems` | the report against `service-load.schema.json` (no caller, no job id, counts and durations only) |
+| `load_view(well_known)`, `load_extension_rules(well_known)` | `loadView`, `loadExtensionRules` | the declaration as a reader reads it, and FAC-SEM-133: an invalid one is treated as not declared and reported |
+| `load_extension(path, window_seconds, limits)` | `loadExtension({path, windowSeconds, limits})` | the `extensions` entry a service declares; raises `ServiceError` on one a reader would hide |
+
+Queue times are UTC instants (`T`, `Z`, at most three fraction digits); report times are RFC 3339 read strictly. A
+node keys every per-caller rule with `job_caller_key`, counts every started job that has not ended (`input_required`
+and paused ones too) as running, and answers another caller's job id `unknown-job`. The text-only `queue-full` result
+and `fabric.job.list` are still the node's own (FAA-103).
 
 <a id="actions"></a>
 

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

@@ -59,7 +59,7 @@ A module imports only modules listed before it in `kit.json`, so the kit has no
 | L0 | `fabric_time` | strict RFC 3339, UTC days, formatting, day windows, the clock ([dates](#dates-and-times)) |
 | L0 | `fabric_identifiers` | identifier equality by normal form (DEC-0076) |
 | L0 | `fabric_secrets` | the contract's one credential detector (DEC-0044) |
-| L0 | `fabric_peer_owner` | which OS account owns each end of a loopback connection, from the computer's socket table (DEC-0154 HA-2, FAA-226): `listener`, `server_end`, `peer`, `CheckedHTTPConnection`; the Python file is Project Observatory's `peer_owner.py` 1.1.0 vendored from commit `f86f0622` with the readings its header names (`1.1.0+kit.3`), the Node twin reads netstat, `/proc` and the owner SID where Python reads `sysctl`, `/proc` and `GetExtendedTcpTable`; on a restricted macOS table (FAA-267) a caller may vouch with a pid it started, proved by `lsof -p` |
+| L0 | `fabric_peer_owner` | which OS account owns each end of a loopback connection, from the computer's socket table (DEC-0154 HA-2, FAA-226): `listener`, `server_end`, `peer`, `CheckedHTTPConnection`; the Python file is Project Observatory's `peer_owner.py` 1.1.0 vendored from commit `f86f0622` with the readings its header names (`1.1.0+kit.4`), the Node twin reads netstat, `/proc` and the owner SID where Python reads `sysctl`, `/proc` and `GetExtendedTcpTable`; on a restricted macOS table (FAA-267) a caller may vouch with a pid it started, proved by `lsof -p` |
 | L0 | `fabric_tailnet` | who calls an agent behind `tailscale serve` and what that person may open (FAA-297): `Tailscale-User-Login` only on the agent's own serve listener from a loopback peer, groups from a generated `tailnet-perimeter/1` file, a personal SHA-256-stored key for MCP no wider than the groups; `authorize`, `load_perimeter`, `load_keys`, `hash_key`, refusals 401/403 with a code ([surfaces-and-auth.md](surfaces-and-auth.md#behind-tailscale-serve)) |
 | L1 | `fabric_crypto` | Ed25519 signing (a Montgomery ladder that does not branch on the key) and verification, P-256 verification, base64url, sha256 |
 | L1 | `fabric_base` | the protocol name, `ServiceError`, small shared helpers |
@@ -78,6 +78,7 @@ A module imports only modules listed before it in `kit.json`, so the kit has no
 | L3 | `fabric_connections` | what an agent uses, `fabric-connections/0.1`: the reference reading and the declaration (DEC-0096, FAC-SEM-127) |
 | L3 | `fabric_a2a` | the reading side of an A2A Agent Card: `surfaces.a2a` as the schema reads it, and what a public card must not carry (DEC-0122) |
 | L3 | `fabric_page_links` | a service's pages as Fabric Dashboards' open_link: build and read it, a raw local address, FAC-SEM-143 on a link and on a URL-mode input request (DEC-0123); the Python twin reads URLs as WHATWG does by hand |
+| L3 | `fabric_load` | the call queue and the load report of DEC-0104 (FAA-289): `job_caller_key`, `next_queued_job`, `admit_job`, `queue_status_message`, `read_queue_position`, FAC-SEM-131 to 133, the `service-load/1` and `extensions/load/0.1` shapes, `load_extension`; imports `fabric_connections` for ajv's `date-time` ([interop](interop.md#a-nodes-call-queue)) |
 | L3 | `fabric_lock` | the instance lock and the supervisor marker (LC-01, DEC-0057) |
 | L3 | `fabric_usage` | usage receipts, the ledger, the usage report, attribution, spending limits ([usage](usage.md)) |
 | L3 | `fabric_backups` | settings backups (DEC-0025) |
@@ -105,7 +106,8 @@ Beside the kit, not in `kit.json`: the probe (`check_service.py`, `check_service
 `check_service_channel_agent.py`, `check_service_channel_agent_schema.py` and the
 `service-channel-agent-extension.schema.json` it reads at run time), the sample
 (`sample_service.py`, `sample-remote-service.mjs`), `fabric_kit.py` itself and the dashboard tools. Recipes built on
-the kit live in `../recipes/` ([the draft-and-check step of a support agent](../recipes/support-agent/README.md)).
+the kit live in `../recipes/` ([the draft-and-check step of a support agent](../recipes/support-agent/README.md), [a service that is only a
+dashboard](../recipes/dashboard-only/README.md), [a key-delivery door](../recipes/key-delivery-door/README.md)).
 
 ## What 0.39 code keeps