@passioncode-ai/fabric-agent-adapter 0.78.0 → 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

@@ -26,8 +26,10 @@ skill's business (working-with-fabric, `references/project-board.md`).
 
 A **request** is addressed to a Project and one of its capabilities (`video.render`), never to a service. One
 **responder slot** exists per Project and capability; a service holds it under a **`board.respond` grant** the
-operator gives in Fabric (Agents & access): callee `fabric`, capability `board.respond`, resource
-`board:<project id>/<capability>`. A pid, a descriptor or a localhost origin authorizes nothing.
+operator gives in Fabric (Settings → Agent access): callee `fabric`, capability `board.respond`, resource
+`board:<project id>/<capability>`. A pid, a descriptor or a localhost origin authorizes nothing. The capability is
+never `project.work`: DEC-0140 PR-1 reserves it for a Project's primary responder, a coding session, and `Responder`
+refuses it with `invalid_arguments` (FAA-244).
 
 1. Ask once, through the hub's door: `HubClient().request_board_access(agent_id, project_id, [capability], reason)`
    (`requestBoardAccess`). Keep the answer's `pollSecret` in memory or a 0600 file.
@@ -37,8 +39,10 @@ operator gives in Fabric (Agents & access): callee `fabric`, capability `board.r
 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 maps that refusal, as any transport
-   failure, to `board.down` with reason `unreachable` until FAA-252). A missing grant is `HubError` 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.
 
 ## Wiring it into the service
@@ -211,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),
@@ -302,7 +307,7 @@ held and not transferred). The responder keeps that move instead of undoing it:
   after the slot had moved past the record, reads as a move: the safe side; a slot such a replay took is left to lapse
   unused. A generation written `2.0` is `2`.
 - The operator may move the slot back to this session in Fabric (DEC-0140 PR-2), which this client cannot hear. No
-  Fabric release offers the operator's move yet (Fabric 0.3.15 has none: the control is CT-174's in Fabric, its agent twin CT-181 in the contract, then CT-125),
+  Fabric release through v0.3.19 (2026-11-11) offers the operator's move (the control is CT-174's in Fabric, its agent twin CT-181 in the contract, then CT-125),
   so today every move is another session taking the slot and take-back is the route back; the check below is ready
   for the move. While
   a slot is moved the responder reads `com.status` once a renewal (20 s) and, when the slot's generation is past the

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

@@ -81,7 +81,7 @@ const answer = await client.chat(messages, { model, fallback, maxTokens: 800 });
 | Receipts | every status-200 answer records one, and so does an attempt that may have been billed without an answer to read (a timeout, a cut or refused connection, a 200 over the size cap or not JSON: no tokens, `costUsd: null`, `tokensMeasured: false`; over-counting a refused connection is the safe side): the served model, the provider's tokens (cache reads and writes kept apart), `costUsd` from `usage.cost`, else from the price list (`costBasis: price-list`), else `null` with `tokensMeasured: false`; `route: key`, the client's `project_id` and the call's `task_run_id`. A request the provider answered with a 4xx or 5xx records nothing: it was not billed |
 | What is an answer | `finish_reason` `stop` or `tool_calls` with content or tool calls; `error` is retried on the same model; `length` (the budget ran out, reasoning included), `content_filter` and empty content go to the fallback |
 | Retries | 408, 425, 429, 500, 502, 503, 504 and connection errors on the same model, `retries` times (default 1), `Retry-After` honoured, within one deadline (`deadline_s` 120) for the whole call |
-| Stop at once | 401, 402 and 403 (kinds `auth`, `payment`): a key, credit or permission problem is the same on every model |
+| Stop at once | 401, 402 and 403 (kinds `auth`, `payment`): a key, credit or permission problem is the same on every model; a loopback `base_url` another OS account's process holds (kind `foreign-user`, nothing sent, nothing counted): the fallback would reach the same listener (FAA-257) |
 | The fallback | required, of another vendor (the part before `/` differs) |
 | Content | text only: a string, null, or parts that are all `{"type": "text"}`; an image, audio or file part is refused (`config`), because what it is billed cannot be bounded from its bytes |
 | What the ceiling does not cover | the `provider` routing param can send a call to a provider priced above the catalog; two `Client` objects sharing one ledger each hold only their own calls in flight, so give an agent one client per key |
@@ -90,7 +90,7 @@ const answer = await client.chat(messages, { model, fallback, maxTokens: 800 });
 | Request body | `model`, `messages`, `max_tokens`, `usage: {include: true}` and your params (temperature, reasoning, response_format, tools); `stream`, `model`, `messages`, `max_tokens` and `usage` as params are refused |
 
 `OpenRouterError.attempts` lists every attempt as `{model, status, outcome}` (`answered`, `retry`, `error`,
-`length`, `filtered`, `empty`, `refused`, `bad-answer`, `auth`, `payment`); nothing in it holds the key or the
+`length`, `filtered`, `empty`, `refused`, `bad-answer`, `auth`, `payment`, `foreign-user`); nothing in it holds the key or the
 prompt. `totals(receipts)` gives calls, priced spend and unpriced calls for a dashboard line. Choosing the models
 themselves: creating-fabric-agents, `references/models-and-providers.md`.
 

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

@@ -59,7 +59,7 @@ Never edit the copied files: the page's own rules go in its own stylesheet, cons
 | Grids | `.fd-grid` (cards, 320 px columns), `.fd-grid--tiles` (160 px), `.fd-grid--wide` (480 px); `--fd-col` sets your own |
 | Wide content | `<div class="fd-scroll" data-fd-label="Jobs table"><table class="fd-table">…</table></div>`, `<pre class="fd-scroll">` |
 | Atoms | `.fd-card`, `.fd-tile`, `.fd-chip` + `.fd-dot` + `.fd-s-ok\|warn\|danger\|info`, `.fd-btn`, `.fd-btn--primary`, `.fd-input`, `.fd-select`, `.fd-banner`, `.fd-empty`, `.fd-pairs` |
-| Navigation that folds | with the script, links that do not fit move into **More** (`data-fd-more-label` names it, `data-fd-no-fold` keeps a nav as is); the summary names the current section (`aria-current`) or counts the folded links, and the fit is measured with that text in place. Moving `aria-current` refits on its own; after changing the links' text call `FabricDashboard.refreshNav(nav)` (since 1.1.3) |
+| Navigation that folds | with the script, links that do not fit move into **More** (`data-fd-more-label` names it, `data-fd-no-fold` keeps a nav as is); the summary names the current section (`aria-current`) or counts the folded links, and the fit is measured with that text in place. Moving `aria-current` refits on its own; after changing the links' text call `FabricDashboard.refreshNav(nav)` (since 1.1.3). Since 1.1.6 a resize refits in the next animation frame and only when the nav's width changed, and the chrome's `--fd-chrome-h` and `--fd-chrome-top` are written the same way and only when they change, so no observer resizes what it watches inside its own callback (WebKit's "ResizeObserver loop completed with undelivered notifications" at 390 px, seen on a service page) |
 | Own appearance controls | `<select data-fd-theme-picker>`, `<select data-fd-scheme-picker>` (the script fills them; hidden while the host owns appearance) |
 
 Tokens are the workbench layer (`--bg`, `--panel`, `--panel-2`, `--ink`, `--muted`, `--border`,

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,17 +119,52 @@ 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.
 A separately labelled copyable link for diagnosis is not an open action.
 
-Add this check to the generated project's dashboard completion/notification
-renderer before delivery. A raw-HTTP primary action with an available host is the
-negative fixture; a valid native action is the positive one. Keep diagnostics
-separate. This gate checks structured actions, not arbitrary prose: a CLI invocation
-or instructions alone do not prove all final answers from every agent are filtered.
+The gate is **agent-side**: the agent runs it from this skill's directory before it
+delivers an action. It is never copied into the generated project and never run by
+that project's CI: the adapter's versioned plugin folder has no stable path there, so
+its result in a project's pipeline would always be NOT_RUN. A raw-HTTP primary action
+with an available host is the gate's negative fixture; a valid native action is the
+positive one. Keep diagnostics separate. This gate checks structured actions, not
+arbitrary prose: a CLI invocation or instructions alone do not prove all final answers
+from every agent are filtered.
+
+The generated project pins the same negative fixture in its own test suite, without
+calling the gate: a test that renders its completion and notification output with an
+available host and fails when a raw loopback `http_url` or a legacy `open?service=`
+link appears in it. The snippet is self-contained; `render` stands for the project's
+own renderer:
+
+```python
+import re
+import unittest
+
+RAW_LOOPBACK = re.compile(r"https?://(?:127\.0\.0\.1|localhost|\[::1\])")
+LEGACY = "fabric-dashboards://open?service="
+RESOLVED = {"service": "example-agent.default",
+            "open_link": "fabric-dashboards://service/example-agent.default?path=%2Fdashboard",
+            "http_url": "http://127.0.0.1:47195/dashboard"}
+
+
+def render(resolved, host_state):  # replace with the project's completion/notification renderer
+    raise NotImplementedError
+
+
+class RenderedDashboardLinks(unittest.TestCase):
+    def test_rendered_output_has_no_raw_loopback_or_legacy_link(self):
+        out = render(RESOLVED, host_state="available")
+        self.assertIn(RESOLVED["open_link"], out)
+        self.assertIsNone(RAW_LOOPBACK.search(out), out)
+        self.assertNotIn(LEGACY, out)
+```
 
 ## Degradation
 

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

@@ -127,7 +127,10 @@ page as Fabric Dashboards' `open_link`; both kits carry the same sentence. The g
 
 `JwksCache` holds the estate's key set at most 10 minutes and, on a `kid` it does not hold, re-reads at most once
 a minute (DL-15), and waits 10 s after a failed read before trying again; after 10 minutes without a successful read it answers nothing, and the verifier says
-`issuer-unavailable`. It reads https, http on loopback only, or a file; a URL with credentials is refused. The
+`issuer-unavailable`. It reads https, http on loopback only, or a file; a URL with credentials is refused. On loopback
+http it tells the listener's owner from the socket table before a byte is sent and reads no key set another OS
+account's process serves (DEC-0154 HA-2, `fabric_peer_owner`; the read fails `foreign-user`, so the set stays unread,
+FAA-255); no proxy from the environment is used there. Where the socket table hides other processes (macOS 27.2 with an ad-hoc-signed Homebrew Python, FAA-267), the owner cannot be told, so a loopback key set fails `foreign-user` and every delegated call is refused `issuer-unavailable`: run the service on Apple's `/usr/bin/python3`, or give the verifier the key set as a file. The
 Python kit also refuses, https included, a URL holding a space or ASCII control character before its first `#` (it
 reads the URL up to there, as Node does), or a character outside ASCII in its path or query (urllib would send it
 and every read fail; a trailing ASCII space or line break is trimmed as urllib reads it; a Unicode space ending the
@@ -160,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