@passioncode-ai/fabric-agent-adapter 0.8.3 → 0.10.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-service.mjs

@@ -11,6 +11,11 @@ import path from 'node:path';
 
 export const PROTOCOL = 'fabric-service/0.1';
 export const EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/service/0.1';
+// The embedded dashboard declaration (fabric-dashboard/0.1, DEC-0036 ED-9), under the well-known
+// document's `extensions`. The kit is assets/dashboard-kit; its version is the one in kit.json.
+export const DASHBOARD_EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1';
+export const DASHBOARD_KIT = 'fabric-dashboard-kit@1.0.0';
+export const REFERENCE_THEMES = ['graphite', 'fabric', 'paper', 'forest', 'ocean', 'ember', 'contrast'];
 export const EXIT_ALREADY_RUNNING = 75;
 // Lifecycle contract (fabric-workspace knowledge/lifecycle.md), the same values as fabric_service.py.
 // A launchd-supervised copy that finds the lock held backs off in-process before its exit 75 (LC-03).
@@ -339,7 +344,45 @@ export function removeDescriptor(id, instance = 'default', dir = servicesDir())
 
 // --- well-known and events ------------------------------------------------------------
 
-export function buildWellKnown({ id, instance, name, version, build, startedAt, status, degraded = [], surfaces, summary, updateAvailable = null, pid = process.pid }) {
+const THEME_ID = /^[a-z][a-z0-9-]{0,31}$/;
+const KIT_REF = /^[a-z][a-z0-9-]{0,63}@(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/;
+
+// What makes value not a valid ED-9 declaration (service-dashboard-extension.schema.json).
+export function dashboardExtensionProblems(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return ['the declaration is not an object'];
+  const out = [];
+  const extra = Object.keys(value).filter((k) => !['minWidth', 'appearance', 'themes', 'kit'].includes(k)).sort();
+  if (extra.length) out.push(`unknown field(s): ${extra.join(', ')}`);
+  const w = value.minWidth;
+  if (!Number.isInteger(w)) out.push('minWidth is required and must be a whole number of CSS pixels');
+  else if (w < 360 || w > 1280) out.push(`minWidth ${w} is outside 360…1280`);
+  if ('appearance' in value) {
+    const a = value.appearance;
+    if (!Array.isArray(a) || a.length > 2 || new Set(a).size !== a.length || a.some((x) => x !== 'scheme' && x !== 'theme')) out.push('appearance is a list of distinct fields from scheme, theme');
+  }
+  if ('themes' in value) {
+    const t = value.themes;
+    if (!Array.isArray(t) || t.length < 1 || t.length > 32 || new Set(t).size !== t.length || t.some((x) => typeof x !== 'string' || !THEME_ID.test(x))) out.push('themes is 1…32 distinct theme ids matching ^[a-z][a-z0-9-]{0,31}$');
+  }
+  if ('kit' in value && !(typeof value.kit === 'string' && KIT_REF.test(value.kit))) out.push(`kit is name@semver, for example ${DASHBOARD_KIT}`);
+  return out;
+}
+
+// The `extensions` entry a dashboard built from the kit declares (DEC-0036 ED-9). Declare it only
+// when the page meets ED-1…ED-6 — check_dashboard_layout.mjs measures that.
+export function dashboardExtension({ minWidth = 360, appearance = ['scheme', 'theme'], themes = REFERENCE_THEMES, kit = DASHBOARD_KIT } = {}) {
+  const value = { minWidth };
+  if (appearance?.length) value.appearance = [...appearance];
+  if (themes?.length) value.themes = [...themes];
+  if (kit) value.kit = kit;
+  const problems = dashboardExtensionProblems(value);
+  if (problems.length) throw new ServiceError(`Dashboard declaration: ${problems.join('; ')}.`);
+  return { [DASHBOARD_EXTENSION_KEY]: value };
+}
+
+// `extensions` is kept as given (a reader ignores keys it does not know); a dashboard declaration in
+// it must be valid (dashboardExtension builds one).
+export function buildWellKnown({ id, instance, name, version, build, startedAt, status, degraded = [], surfaces, summary, updateAvailable = null, pid = process.pid, extensions }) {
   if (!STATUSES.includes(status)) throw new ServiceError(`status must be one of ${STATUSES.join(', ')}.`);
   if (!surfaces?.events) throw new ServiceError('surfaces.events is required.');
   if (!(build?.commit || build?.digest)) throw new ServiceError('build needs a commit or a digest.');
@@ -353,6 +396,13 @@ export function buildWellKnown({ id, instance, name, version, build, startedAt,
     update: { available: updateAvailable },
   };
   if (summary?.length) doc.summary = summary.slice(0, 6);
+  if (extensions && Object.keys(extensions).length) {
+    if (DASHBOARD_EXTENSION_KEY in extensions) {
+      const problems = dashboardExtensionProblems(extensions[DASHBOARD_EXTENSION_KEY]);
+      if (problems.length) throw new ServiceError(`Dashboard declaration: ${problems.join('; ')}.`);
+    }
+    doc.extensions = { ...extensions };
+  }
   return doc;
 }
 
@@ -657,15 +707,41 @@ export function pruneReleases(releasesDir, { keep = 2, current } = {}) {
 
 // --- operator login -------------------------------------------------------------------
 
+/** DEC-0039 (service.md "The session's lifetime"): the longest a service may keep an operator session. */
+export const OPERATOR_SESSION_IDLE_SECONDS = 12 * 60 * 60;
+export const OPERATOR_SESSION_MAX_SECONDS = 7 * 24 * 60 * 60;
+
+// Compare bytes, not UTF-16 units: a non-ASCII value of the right length must be a refusal, not a RangeError.
+const safeEqual = (a, b) => {
+  const x = Buffer.from(String(a)), y = Buffer.from(String(b));
+  return x.length === y.length && crypto.timingSafeEqual(x, y);
+};
+const sessionBound = (value, longest) => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) throw new ServiceError('a session bound must be a finite number of seconds.');
+  return Math.min(Math.trunc(value), longest);
+};
+
+// Single-use login codes, and operator sessions with the DEC-0039 lifetime: a session ends 12 h after its
+// last use, 7 days after the code was redeemed, on logout, and when the descriptor token rotates. The server
+// enforces all four: the cookie carries a signed claim (session id, sign-in time, token revision) and the
+// code store keeps a record per session (last use, logout). Rotating the key with revokeAll() ends every one.
 export class LoginCodes {
-  // `stateDir` — a local service keeps codes and the session key in files. An online service
-  // (DEC-0019) usually has no durable disk: pass `stateDir = null` with `{ store, key }` — `store`
-  // like `new MemoryCodeStore()` (a restart forgets every code, so none can be replayed) and
-  // `key` a Buffer from a platform secret, so sessions survive a deploy.
-  constructor(stateDir, ttlSeconds = 120, { store = null, key = null } = {}) {
+  // `stateDir` — a local service keeps codes, sessions and the session key in files. An online service
+  // (DEC-0019) usually has no durable disk: pass `stateDir = null` with `{ store, key }` — `store` like
+  // `new MemoryCodeStore()` and `key` a Buffer from a platform secret. A memory store forgets codes AND
+  // sessions on a restart, so a deploy signs the operator out (the host signs in again on the page's 401);
+  // pass a durable store to keep sessions. `token` is the descriptor token, or a function returning the
+  // current one: a session begun under one token is refused once it rotates. A service MAY shorten
+  // `idleSeconds` or `maxSeconds`, never lengthen them.
+  constructor(stateDir, ttlSeconds = 120, { store = null, key = null, token = null,
+    idleSeconds = OPERATOR_SESSION_IDLE_SECONDS, maxSeconds = OPERATOR_SESSION_MAX_SECONDS, clock = () => Date.now() / 1000 } = {}) {
     this.ttl = Math.min(ttlSeconds, 120);
+    this.idleSeconds = sessionBound(idleSeconds, OPERATOR_SESSION_IDLE_SECONDS);
+    this.maxSeconds = sessionBound(maxSeconds, OPERATOR_SESSION_MAX_SECONDS);
     this.store = store;
     this.fixedKey = key;
+    this.token = token;
+    this.clock = clock;
     if (stateDir) {
       this.dir = ensurePrivateDir(stateDir);
       this.keyPath = path.join(this.dir, 'session.key');
@@ -688,7 +764,7 @@ export class LoginCodes {
   }
 
   save(codes) {
-    const horizon = Date.now() / 1000 - 3600;
+    const horizon = this.clock() - 3600;
     const kept = Object.fromEntries(Object.entries(codes).filter(([, v]) => (v.expires ?? 0) > horizon));
     if (this.store) { this.store.save(kept); return; }
     atomicWrite(this.codesPath, JSON.stringify(kept), 0o600);
@@ -696,7 +772,7 @@ export class LoginCodes {
 
   issue() {
     const code = crypto.randomBytes(24).toString('base64url');
-    const expires = Date.now() / 1000 + this.ttl;
+    const expires = this.clock() + this.ttl;
     const codes = this.load();
     codes[crypto.createHash('sha256').update(code).digest('hex')] = { expires, used: false };
     this.save(codes);
@@ -712,19 +788,66 @@ export class LoginCodes {
     if (!entry || entry.used) return null;
     entry.used = true;
     this.save(codes);
-    if (entry.expires < Date.now() / 1000) return null;
+    const now = this.clock();
+    if (entry.expires < now) return null;
     const session = crypto.randomBytes(18).toString('base64url');
-    return `${session}.${crypto.createHmac('sha256', this.key()).update(session).digest('hex')}`;
+    const signedInAt = Math.trunc(now);
+    codes[LoginCodes.recordKey(session)] = { expires: signedInAt + this.maxSeconds, signedInAt, lastUsedAt: now };
+    this.save(codes);
+    const claim = `v2.${session}.${signedInAt}.${this.tokenRevision()}`;
+    return `${claim}.${this.mac(claim)}`;
   }
 
+  /** True while the session is live; a use within the bounds refreshes the idle bound. */
   sessionValid(value) {
-    if (!value || !value.includes('.')) return false;
-    const i = value.lastIndexOf('.');
-    const expected = crypto.createHmac('sha256', this.key()).update(value.slice(0, i)).digest('hex');
-    const mac = value.slice(i + 1);
-    return mac.length === expected.length && crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(expected));
+    const parsed = this.parse(value);
+    if (!parsed) return false;
+    const [session, signedInAt] = parsed;
+    const now = this.clock();
+    if (now >= signedInAt + this.maxSeconds) return false;
+    const codes = this.load();
+    const record = codes[LoginCodes.recordKey(session)];
+    if (!record || record.signedInAt !== signedInAt || record.loggedOutAt != null) return false;
+    const last = Number(record.lastUsedAt ?? 0);
+    if (now >= last + this.idleSeconds) return false;
+    if (now - last >= Math.min(60, Math.max(1, Math.trunc(this.idleSeconds / 10)))) {
+      record.lastUsedAt = now;
+      this.save(codes);
+    }
+    return true;
   }
 
+  /** End this session on the server; clear the browser's copy with expiredSessionCookieHeader(). */
+  logout(value) {
+    const parsed = this.parse(value);
+    if (!parsed) return false;
+    const codes = this.load();
+    const record = codes[LoginCodes.recordKey(parsed[0])];
+    if (!record || record.signedInAt !== parsed[1] || record.loggedOutAt != null) return false;
+    record.loggedOutAt = this.clock();
+    this.save(codes);
+    return true;
+  }
+
+  parse(value) {
+    if (typeof value !== 'string' || !/^[\x21-\x7e]*$/.test(value)) return null;
+    const parts = value.split('.');
+    if (parts.length !== 5 || parts[0] !== 'v2' || !parts[1] || !/^\d+$/.test(parts[2])) return null;
+    if (!safeEqual(parts[4], this.mac(parts.slice(0, 4).join('.')))) return null;
+    if (!safeEqual(parts[3], this.tokenRevision())) return null;
+    return [parts[1], Number(parts[2])];
+  }
+
+  mac(claim) { return crypto.createHmac('sha256', this.key()).update(claim).digest('hex'); }
+
+  tokenRevision() {
+    const token = typeof this.token === 'function' ? this.token() : this.token;
+    if (!token) return '-';
+    return crypto.createHmac('sha256', this.key()).update(`token-revision\0${token}`).digest('hex').slice(0, 16);
+  }
+
+  static recordKey(session) { return `s:${crypto.createHash('sha256').update(session).digest('hex')}`; }
+
   revokeAll() {
     if (this.fixedKey) throw new ServiceError('a platform-held session key is rotated on the platform, not here.');
     atomicWrite(this.keyPath, crypto.randomBytes(32), 0o600);
@@ -738,9 +861,12 @@ export class MemoryCodeStore {
   save(codes) { this.codes = JSON.parse(JSON.stringify(codes)); }
 }
 
-export const sessionCookieHeader = (value, maxAge = 30 * 86400) => `${SESSION_COOKIE}=${value}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${maxAge}`;
+/** The cookie lives no longer than the absolute bound (DEC-0039); the server ends it sooner. */
+export const sessionCookieHeader = (value, maxAge = OPERATOR_SESSION_MAX_SECONDS) => `${SESSION_COOKIE}=${value}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${maxAge}`;
 /** DEC-0019: the remote cookie — `__Host-` name, Secure, no Domain, Path=/. */
-export const remoteSessionCookieHeader = (value, maxAge = 30 * 86400) => `${REMOTE_SESSION_COOKIE}=${value}; Path=/; Secure; HttpOnly; SameSite=Strict; Max-Age=${maxAge}`;
+export const remoteSessionCookieHeader = (value, maxAge = OPERATOR_SESSION_MAX_SECONDS) => `${REMOTE_SESSION_COOKIE}=${value}; Path=/; Secure; HttpOnly; SameSite=Strict; Max-Age=${maxAge}`;
+/** The header that clears the browser's session cookie, sent with a logout. */
+export const expiredSessionCookieHeader = (remote = false) => (remote ? remoteSessionCookieHeader : sessionCookieHeader)('', 0);
 
 /**
  * DEC-0019: the request guard of an online service. `origin` is the service's own origin

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_service.py

@@ -40,6 +40,11 @@ import urllib.request
 
 PROTOCOL = "fabric-service/0.1"
 EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/service/0.1"
+# The embedded dashboard declaration (fabric-dashboard/0.1, DEC-0036 ED-9), under the well-known
+# document's `extensions`. The kit is assets/dashboard-kit; its version is the one in kit.json.
+DASHBOARD_EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1"
+DASHBOARD_KIT = "fabric-dashboard-kit@1.0.0"
+REFERENCE_THEMES = ("graphite", "fabric", "paper", "forest", "ocean", "ember", "contrast")
 EXIT_ALREADY_RUNNING = 75
 # Lifecycle contract (fabric-workspace knowledge/lifecycle.md). A launchd-supervised copy that finds
 # the lock held backs off in-process for this long before its exit 75 (LC-03, F8): under KeepAlive
@@ -58,6 +63,9 @@ DEFAULT_EXIT_TIMEOUT = 15
 LOG_MAX_BYTES = 5 * 1024 * 1024
 LOG_BACKUPS = 5
 LOGIN_CODE_TTL_SECONDS = 120
+# DEC-0039 (service.md "The session's lifetime"): the longest a service may keep an operator session.
+OPERATOR_SESSION_IDLE_SECONDS = 12 * 60 * 60
+OPERATOR_SESSION_MAX_SECONDS = 7 * 24 * 60 * 60
 EVENTS_DEFAULT_LIMIT = 50
 EVENTS_MAX_LIMIT = 200
 LEVELS = ("info", "notice", "warning", "error")
@@ -701,11 +709,63 @@ def build_info(repo_root: Optional[Path] = None, package_file: Optional[Path] =
     return info
 
 
+_THEME_ID = re.compile(r"^[a-z][a-z0-9-]{0,31}$")
+_KIT_REF = re.compile(r"^[a-z][a-z0-9-]{0,63}@(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$")
+
+
+def dashboard_extension_problems(value: Any) -> List[str]:
+    """What makes value not a valid ED-9 declaration (service-dashboard-extension.schema.json)."""
+    if not isinstance(value, dict):
+        return ["the declaration is not an object"]
+    out: List[str] = []
+    extra = sorted(set(value) - {"minWidth", "appearance", "themes", "kit"})
+    if extra:
+        out.append("unknown field(s): %s" % ", ".join(extra))
+    width = value.get("minWidth")
+    if isinstance(width, bool) or not isinstance(width, int):
+        out.append("minWidth is required and must be a whole number of CSS pixels")
+    elif not 360 <= width <= 1280:
+        out.append("minWidth %d is outside 360…1280" % width)
+    if "appearance" in value:
+        a = value["appearance"]
+        if not isinstance(a, list) or len(a) > 2 or len(set(map(str, a))) != len(a) or any(x not in ("scheme", "theme") for x in a):
+            out.append("appearance is a list of distinct fields from scheme, theme")
+    if "themes" in value:
+        t = value["themes"]
+        if not isinstance(t, list) or not 1 <= len(t) <= 32 or len(set(map(str, t))) != len(t) \
+                or any(not isinstance(x, str) or not _THEME_ID.match(x) for x in t):
+            out.append("themes is 1…32 distinct theme ids matching ^[a-z][a-z0-9-]{0,31}$")
+    if "kit" in value and not (isinstance(value["kit"], str) and _KIT_REF.match(value["kit"])):
+        out.append("kit is name@semver, for example %s" % DASHBOARD_KIT)
+    return out
+
+
+def dashboard_extension(min_width: int = 360, appearance: Sequence[str] = ("scheme", "theme"),
+                        themes: Optional[Sequence[str]] = REFERENCE_THEMES,
+                        kit: Optional[str] = DASHBOARD_KIT) -> Dict[str, Any]:
+    """The `extensions` entry a dashboard built from the kit declares (DEC-0036 ED-9). Declare it only
+    when the page meets ED-1…ED-6 — check_dashboard_layout.mjs measures that."""
+    value: Dict[str, Any] = {"minWidth": min_width}
+    if appearance:
+        value["appearance"] = list(appearance)
+    if themes:
+        value["themes"] = list(themes)
+    if kit:
+        value["kit"] = kit
+    problems = dashboard_extension_problems(value)
+    if problems:
+        raise ServiceError("Dashboard declaration: %s." % "; ".join(problems))
+    return {DASHBOARD_EXTENSION_KEY: value}
+
+
 def build_well_known(*, service_id: str, instance: str, name: str, version: str, build: Dict[str, Any],
                      started_at: str, status: str, degraded: Sequence[Dict[str, str]],
                      surfaces: Dict[str, Any], summary: Optional[Sequence[Dict[str, Any]]] = None,
-                     update_available: Optional[str] = None, pid: Optional[int] = None) -> Dict[str, Any]:
-    """The unauthenticated identity answer. `degraded` is always present; ready means empty."""
+                     update_available: Optional[str] = None, pid: Optional[int] = None,
+                     extensions: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """The unauthenticated identity answer. `degraded` is always present; ready means empty.
+    `extensions` is kept as given (a reader ignores keys it does not know); a dashboard declaration
+    in it must be valid (dashboard_extension builds one)."""
     if status not in STATUSES:
         raise ServiceError("status must be one of %s." % ", ".join(STATUSES))
     degraded = list(degraded)
@@ -724,6 +784,12 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
     }
     if summary:
         doc["summary"] = list(summary)[:6]
+    if extensions:
+        if DASHBOARD_EXTENSION_KEY in extensions:
+            problems = dashboard_extension_problems(extensions[DASHBOARD_EXTENSION_KEY])
+            if problems:
+                raise ServiceError("Dashboard declaration: %s." % "; ".join(problems))
+        doc["extensions"] = dict(extensions)
     return doc
 
 
@@ -1140,17 +1206,35 @@ class Drain:
 # --- operator login ----------------------------------------------------------
 
 class LoginCodes:
-    """Single-use login codes (<=120 s), recorded as used BEFORE they are honoured,
-    and HMAC-signed session cookies revoked by rotating the key."""
+    """Single-use login codes (<=120 s), recorded as used BEFORE they are honoured, and operator
+    sessions with the DEC-0039 lifetime: a session ends 12 h after its last use, 7 days after the code
+    was redeemed, on logout, and when the descriptor token rotates. The server enforces all four: the
+    cookie carries a signed claim (session id, sign-in time, token revision) and the code store keeps a
+    record per session (last use, logout). Rotating the key with revoke_all() ends every session."""
 
     def __init__(self, state_dir: Optional[Path], ttl: int = LOGIN_CODE_TTL_SECONDS, *,
-                 store: Optional["MemoryCodeStore"] = None, key: Optional[bytes] = None):
-        # A local service keeps codes and the key in files. An online one (DEC-0019) usually has no
-        # durable disk: pass state_dir=None with store=MemoryCodeStore() (a restart forgets every
-        # code, so none can be replayed) and key= bytes from a platform secret (sessions survive a deploy).
+                 store: Optional["MemoryCodeStore"] = None, key: Optional[bytes] = None,
+                 token: "Optional[str | Callable[[], str]]" = None,
+                 idle_seconds: int = OPERATOR_SESSION_IDLE_SECONDS,
+                 max_seconds: int = OPERATOR_SESSION_MAX_SECONDS,
+                 clock: Callable[[], float] = time.time):
+        # A local service keeps codes, sessions and the key in files. An online one (DEC-0019) usually has
+        # no durable disk: pass state_dir=None with store=MemoryCodeStore() and key= bytes from a platform
+        # secret. A memory store forgets codes AND sessions on a restart, so a deploy signs the operator
+        # out (the host signs in again on the page's 401); pass a durable store to keep sessions.
+        # token= is the descriptor token, or a callable returning the current one: a session begun under
+        # one token is refused once it rotates. A service MAY shorten either bound, never lengthen one.
         self.ttl = min(ttl, LOGIN_CODE_TTL_SECONDS)
+        self.idle_seconds = _session_bound(idle_seconds, OPERATOR_SESSION_IDLE_SECONDS)
+        self.max_seconds = _session_bound(max_seconds, OPERATOR_SESSION_MAX_SECONDS)
+        # One lock around every load-modify-save, so a concurrent refresh never saves over a logout or a
+        # burned code (a threading server checks sessions on several threads; the instance lock keeps
+        # other processes out of the state directory).
+        self._lock = threading.RLock()
         self._store = store
         self._fixed_key = key
+        self._token = token
+        self._clock = clock
         if state_dir is not None:
             self.dir = ensure_private_dir(Path(state_dir))
             self._key_path = self.dir / "session.key"
@@ -1176,7 +1260,7 @@ class LoginCodes:
             return {}
 
     def _save(self, codes: Dict[str, Any]) -> None:
-        horizon = time.time() - 3600
+        horizon = self._clock() - 3600
         codes = {k: v for k, v in codes.items() if v.get("expires", 0) > horizon}
         if self._store is not None:
             self._store.save(codes)
@@ -1184,39 +1268,101 @@ class LoginCodes:
         atomic_write(self._codes_path, json.dumps(codes).encode(), 0o600)
 
     def issue(self) -> Dict[str, str]:
-        code = secrets.token_urlsafe(24)
-        expires = time.time() + self.ttl
-        codes = self._load()
-        codes[hashlib.sha256(code.encode()).hexdigest()] = {"expires": expires, "used": False}
-        self._save(codes)
-        at = _dt.datetime.fromtimestamp(expires, _dt.timezone.utc).replace(microsecond=0)
-        return {"url": "/fabric/v1/login?code=" + code, "expiresAt": at.isoformat().replace("+00:00", "Z")}
+        with self._lock:
+            code = secrets.token_urlsafe(24)
+            expires = self._clock() + self.ttl
+            codes = self._load()
+            codes[hashlib.sha256(code.encode()).hexdigest()] = {"expires": expires, "used": False}
+            self._save(codes)
+            at = _dt.datetime.fromtimestamp(expires, _dt.timezone.utc).replace(microsecond=0)
+            return {"url": "/fabric/v1/login?code=" + code, "expiresAt": at.isoformat().replace("+00:00", "Z")}
 
     def redeem(self, code: Optional[str]) -> Optional[str]:
         """Return a session cookie value, or None. The code is burned even when it has expired."""
-        if not code or not _CODE.match(code):
+        with self._lock:
+            if not code or not _CODE.match(code):
+                return None
+            digest = hashlib.sha256(code.encode()).hexdigest()
+            codes = self._load()
+            entry = codes.get(digest)
+            if not entry or entry.get("used"):
+                return None
+            entry["used"] = True
+            self._save(codes)
+            now = self._clock()
+            if entry.get("expires", 0) < now:
+                return None
+            session_id = secrets.token_urlsafe(18)
+            signed_in = int(now)
+            codes[self._record_key(session_id)] = {"expires": signed_in + self.max_seconds,
+                                                   "signedInAt": signed_in, "lastUsedAt": now}
+            self._save(codes)
+            claim = "v2.%s.%d.%s" % (session_id, signed_in, self._token_revision())
+            return claim + "." + self._mac(claim)
+
+    def session_valid(self, cookie_value: Optional[str]) -> bool:
+        """True while the session is live; a use within the bounds refreshes the idle bound."""
+        with self._lock:
+            parsed = self._parse(cookie_value)
+            if parsed is None:
+                return False
+            session_id, signed_in = parsed
+            now = self._clock()
+            if now >= signed_in + self.max_seconds:
+                return False
+            codes = self._load()
+            record = codes.get(self._record_key(session_id))
+            if not record or record.get("signedInAt") != signed_in or record.get("loggedOutAt") is not None:
+                return False
+            last = float(record.get("lastUsedAt", 0))
+            if now >= last + self.idle_seconds:
+                return False
+            if now - last >= min(60, max(1, self.idle_seconds // 10)):
+                record["lastUsedAt"] = now
+                self._save(codes)
+            return True
+
+    def logout(self, cookie_value: Optional[str]) -> bool:
+        """End this session on the server: every copy of the cookie is refused from now on. Clear the
+        browser's copy with expired_session_cookie_header(). False when there was no live record."""
+        with self._lock:
+            parsed = self._parse(cookie_value)
+            if parsed is None:
+                return False
+            codes = self._load()
+            record = codes.get(self._record_key(parsed[0]))
+            if not record or record.get("signedInAt") != parsed[1] or record.get("loggedOutAt") is not None:
+                return False
+            record["loggedOutAt"] = self._clock()
+            self._save(codes)
+            return True
+
+    def _parse(self, cookie_value: Optional[str]) -> Optional[Tuple[str, int]]:
+        """The signed claim of a cookie under the current key and token, or None."""
+        if not isinstance(cookie_value, str) or not cookie_value.isascii():
+            return None
+        parts = cookie_value.split(".")
+        if len(parts) != 5 or parts[0] != "v2" or not parts[1] or not parts[2].isdigit():
             return None
-        digest = hashlib.sha256(code.encode()).hexdigest()
-        codes = self._load()
-        entry = codes.get(digest)
-        if not entry or entry.get("used"):
+        claim, mac = ".".join(parts[:4]), parts[4]
+        if not hmac.compare_digest(mac, self._mac(claim)):
             return None
-        entry["used"] = True
-        self._save(codes)
-        if entry.get("expires", 0) < time.time():
+        if not hmac.compare_digest(parts[3], self._token_revision()):
             return None
-        return self._sign(secrets.token_urlsafe(18))
+        return parts[1], int(parts[2])
 
-    def _sign(self, session_id: str) -> str:
-        mac = hmac.new(self._key(), session_id.encode(), hashlib.sha256).hexdigest()
-        return session_id + "." + mac
+    def _mac(self, claim: str) -> str:
+        return hmac.new(self._key(), claim.encode(), hashlib.sha256).hexdigest()
 
-    def session_valid(self, cookie_value: Optional[str]) -> bool:
-        if not cookie_value or "." not in cookie_value:
-            return False
-        session_id, mac = cookie_value.rsplit(".", 1)
-        expected = hmac.new(self._key(), session_id.encode(), hashlib.sha256).hexdigest()
-        return hmac.compare_digest(mac, expected)
+    def _token_revision(self) -> str:
+        token = self._token() if callable(self._token) else self._token
+        if not token:
+            return "-"
+        return hmac.new(self._key(), b"token-revision\0" + token.encode(), hashlib.sha256).hexdigest()[:16]
+
+    @staticmethod
+    def _record_key(session_id: str) -> str:
+        return "s:" + hashlib.sha256(session_id.encode()).hexdigest()
 
     def revoke_all(self) -> None:
         if self._fixed_key is not None:
@@ -1224,6 +1370,13 @@ class LoginCodes:
         atomic_write(self._key_path, secrets.token_bytes(32), 0o600)
 
 
+def _session_bound(value: Any, longest: int) -> int:
+    """A session bound in seconds: a finite number, never longer than the contract's (DEC-0039)."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value != value or value in (float("inf"), float("-inf")):
+        raise ServiceError("a session bound must be a finite number of seconds.")
+    return min(int(value), longest)
+
+
 class MemoryCodeStore:
     """DEC-0019: a login-code store held in memory — for an online service with no durable disk."""
 
@@ -1241,15 +1394,21 @@ SESSION_COOKIE = "fabric_session"
 REMOTE_SESSION_COOKIE = "__Host-fabric_session"
 
 
-def session_cookie_header(value: str, max_age: int = 30 * 86400) -> str:
+def session_cookie_header(value: str, max_age: int = OPERATOR_SESSION_MAX_SECONDS) -> str:
+    """The cookie lives no longer than the absolute bound (DEC-0039); the server ends it sooner."""
     return "%s=%s; Path=/; HttpOnly; SameSite=Strict; Max-Age=%d" % (SESSION_COOKIE, value, max_age)
 
 
-def remote_session_cookie_header(value: str, max_age: int = 30 * 86400) -> str:
+def remote_session_cookie_header(value: str, max_age: int = OPERATOR_SESSION_MAX_SECONDS) -> str:
     """DEC-0019: the remote cookie — __Host- name, Secure, no Domain, Path=/."""
     return "%s=%s; Path=/; Secure; HttpOnly; SameSite=Strict; Max-Age=%d" % (REMOTE_SESSION_COOKIE, value, max_age)
 
 
+def expired_session_cookie_header(remote: bool = False) -> str:
+    """The header that clears the browser's session cookie, sent with a logout."""
+    return (remote_session_cookie_header if remote else session_cookie_header)("", 0)
+
+
 def check_remote_request(origin: str, host: Optional[str], request_origin: Optional[str] = None,
                          sec_fetch_site: Optional[str] = None, forwarded_proto: Optional[str] = None) -> Optional[str]:
     """DEC-0019: the request guard of an online service; returns the refusal sentence or None.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/sample-remote-service.mjs

@@ -27,7 +27,9 @@ if (!origin || k.remoteOriginProblems(origin).length) { console.error(`origin: $
 if (token.length < 16) { console.error('the service token is missing or shorter than 16 characters'); process.exit(2); }
 
 const startedAt = k.nowIso();
-const codes = new k.LoginCodes(null, 120, { store: new k.MemoryCodeStore(), key });
+// DEC-0039: sessions end 12 h after last use, 7 days after sign-in, on logout and when the token rotates.
+// The memory store forgets them on a deploy; the host signs in again on the page's 401.
+const codes = new k.LoginCodes(null, 120, { store: new k.MemoryCodeStore(), key, token });
 const events = [k.makeEvent('1', startedAt, 'service.started', 'info', 'The example agent started.')];
 const tlsSelf = Boolean(args['tls-cert']);
 
@@ -65,6 +67,12 @@ function handler(req, res) {
     if (!session) return send(res, 403, 'This login link has expired or was used. Open the dashboard from Fabric again.', { 'Content-Type': 'text/plain; charset=utf-8' });
     return send(res, 302, null, { Location: '/', 'Set-Cookie': k.remoteSessionCookieHeader(session) });
   }
+  if (req.method === 'POST' && url.pathname === '/logout') {
+    // A browser write: the custom header keeps another site's form from signing the operator out.
+    if (req.headers['x-fabric-request'] !== '1') return send(res, 403, 'Missing request header.', { 'Content-Type': 'text/plain; charset=utf-8' });
+    codes.logout(k.cookieValue(req.headers.cookie, k.REMOTE_SESSION_COOKIE));
+    return send(res, 204, null, { 'Set-Cookie': k.expiredSessionCookieHeader(true) });
+  }
   if (req.method === 'GET' && url.pathname === '/') {
     if (!codes.sessionValid(k.cookieValue(req.headers.cookie, k.REMOTE_SESSION_COOKIE))) return send(res, 401, 'Sign in from Fabric Dashboards.', { 'Content-Type': 'text/plain; charset=utf-8' });
     return send(res, 200, '<!doctype html><meta charset="utf-8"><title>Example Agent</title><h1>Example Agent</h1>', { 'Content-Type': 'text/html; charset=utf-8', 'Content-Security-Policy': "default-src 'none'" });