@suveren/gateway 0.12.0 → 0.13.1

package/lib/policy.mjs

@@ -0,0 +1,369 @@
+/**
+ * Managed-settings policy — IT-controlled overrides that an employee cannot
+ * change locally (W3 of the Windows installer track; see
+ * suveren-as/docs/work-plan.md, "Added 2026-10-02 — Windows installer").
+ *
+ * Sources, highest precedence first:
+ *   1. Windows registry `HKLM\SOFTWARE\Policies\Suveren\Gateway`, then
+ *      `HKCU\SOFTWARE\Policies\Suveren\Gateway` (HKLM wins over HKCU).
+ *      Read via `reg query` (child_process) — no native modules. Skipped
+ *      entirely on non-Windows.
+ *   2. A JSON file: `%ProgramData%\Suveren\gateway-policy.json` (Windows),
+ *      `/Library/Application Support/Suveren/gateway-policy.json` (macOS),
+ *      `/etc/suveren/gateway-policy.json` (Linux) — overridable for tests
+ *      via `SUVEREN_POLICY_FILE`.
+ *
+ * A key present in EITHER source is LOCKED: every resolver in this codebase
+ * (resolveAsUrl, resolveCaFile, resolvePinTls, resolveProxyUrl,
+ * resolveSimulation / isSimulationMode) must return the policy value
+ * regardless of env var, saved config.json, or CLI flag — see those
+ * modules' own doc comments for where this is wired in. Overall precedence:
+ * policy > env > saved config > defaults.
+ *
+ * `Proxy` is the one key that OVERRIDES an environment variable rather than
+ * merely out-ranking a saved value: on a Windows company laptop the proxy is
+ * set in system settings, not `HTTP_PROXY`/`HTTPS_PROXY` — see
+ * bundle/server.js, which sets both env vars from the policy value
+ * unconditionally when `Proxy` is locked (every other locked key has no env
+ * tier to override in the first place). `NoProxy` is read the same way but
+ * has no saved-config/CLI counterpart at all — NO_PROXY stays env-only
+ * except for this one override.
+ *
+ * Registry value names = JSON file keys (PascalCase, matching what an IT
+ * admin would see in either place): AsUrl, CaFile, PinTls, Proxy, NoProxy,
+ * Simulation, InstallMethod.
+ *
+ * Mirrored (same logic, duplicated — no shared runtime package between the
+ * CLI and the two apps, see config.mjs's doc comment for the established
+ * pattern) in `apps/mcp-server/src/lib/policy.ts` and
+ * `apps/control-plane/src/lib/policy.ts`. Keep all three in step.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const POLICY_KEYS = ['AsUrl', 'CaFile', 'PinTls', 'Proxy', 'NoProxy', 'Simulation', 'InstallMethod'];
+
+/** The documented production path, relative to the hive — never changes for
+ *  a real install. Overridable ONLY via `SUVEREN_POLICY_REGISTRY_KEY`, which
+ *  exists purely so `gateway-policy-windows-registry.test.ts` can point at a
+ *  unique per-run key instead of the real one: `pnpm -r test` runs every
+ *  workspace package in parallel, so a test writing to the REAL key would
+ *  race every OTHER package's tests reading the real registry on the same
+ *  Windows CI runner at the same time (this raced in practice — see
+ *  `SUVEREN_POLICY_REGISTRY` below for the other half of the fix). */
+const DEFAULT_REGISTRY_BASE_KEY = 'SOFTWARE\\Policies\\Suveren\\Gateway';
+
+/** The full `HIVE\base\key` path `reg query`/`reg add` operate on. A pure
+ *  function (no I/O) so a test can assert the default without mocking
+ *  anything — see gateway-policy.test.ts's "documented default paths". */
+export function registryKeyPath(hive) {
+  const baseKey = process.env.SUVEREN_POLICY_REGISTRY_KEY || DEFAULT_REGISTRY_BASE_KEY;
+  return `${hive}\\${baseKey}`;
+}
+
+/**
+ * Validate + normalize a candidate Authority Server URL — the SAME rule
+ * `config set as-url` enforces (see config.mjs's validateAsUrl), duplicated
+ * rather than imported so this module has no dependency on config.mjs (the
+ * TS mirrors of each live in different files entirely).
+ */
+function validateAsUrl(candidate) {
+  const trimmed = (candidate ?? '').trim();
+  if (!trimmed) return { ok: false, error: 'The Authority Server URL is empty.' };
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return { ok: false, error: `"${trimmed}" is not a valid URL.` };
+  }
+  const isLocalHttp =
+    parsed.protocol === 'http:' && (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1');
+  if (parsed.protocol !== 'https:' && !isLocalHttp) {
+    return {
+      ok: false,
+      error: `"${trimmed}" must use https:// (http:// is only allowed for http://localhost or http://127.0.0.1).`,
+    };
+  }
+  let normalized = `${parsed.origin}${parsed.pathname}${parsed.search}${parsed.hash}`;
+  if (normalized.endsWith('/') && normalized !== `${parsed.origin}/`) {
+    normalized = normalized.slice(0, -1);
+  } else if (normalized === `${parsed.origin}/`) {
+    normalized = parsed.origin;
+  }
+  return { ok: true, url: normalized };
+}
+
+/** Same rule as config.mjs's validateCaFile: must exist on disk. Resolved
+ *  against cwd like the CLI flag is — a policy-set relative path is
+ *  unusual, but behaving consistently with `config set ca-file` beats a
+ *  second rule nobody remembers. */
+function validateCaFile(candidate) {
+  const trimmed = (candidate ?? '').trim();
+  if (!trimmed) return { ok: false, error: 'The CA file path is empty.' };
+  if (!existsSync(trimmed)) return { ok: false, error: `No file at "${trimmed}".` };
+  return { ok: true, path: trimmed };
+}
+
+/** Same rule as config.mjs's validateProxyUrl: http:// or https:// only. */
+function validateProxyUrl(candidate) {
+  const trimmed = (candidate ?? '').trim();
+  if (!trimmed) return { ok: false, error: 'The proxy URL is empty.' };
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return { ok: false, error: `"${trimmed}" is not a valid URL.` };
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return { ok: false, error: `"${trimmed}" must use http:// or https://.` };
+  }
+  return { ok: true, url: trimmed };
+}
+
+/** Accepts a JSON boolean, or the DWORD-style 0/1 (as a number OR a string,
+ *  since the registry parser below hands back numbers but a hand-edited
+ *  JSON file might use either). Returns undefined — not a default — for
+ *  anything else, so the caller can tell "not a boolean" from "false". */
+function coerceBoolean(value) {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (value === 0) return false;
+    if (value === 1) return true;
+    return undefined;
+  }
+  if (typeof value === 'string') {
+    const v = value.trim().toLowerCase();
+    if (v === 'true' || v === '1') return true;
+    if (v === 'false' || v === '0') return false;
+  }
+  return undefined;
+}
+
+// ─── Registry (Windows only) ────────────────────────────────────────────
+
+/**
+ * Parse `reg query "HKLM\...\Gateway"` stdout. Real output looks like:
+ *
+ *   HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Suveren\Gateway
+ *       AsUrl    REG_SZ    https://as.company.internal
+ *       PinTls    REG_DWORD    0x1
+ *
+ * Value lines are 4-space-indented; columns are separated by runs of
+ * whitespace. REG_DWORD values print as hex ("0x1"), parsed to a number
+ * here so coerceBoolean can treat it like any other 0/1.
+ */
+export function parseRegQueryOutput(stdout) {
+  const out = {};
+  const lineRe = /^ {4}(\S+)\s+(REG_SZ|REG_EXPAND_SZ|REG_DWORD|REG_QWORD|REG_BINARY|REG_MULTI_SZ)\s+(.*)$/;
+  for (const line of stdout.split(/\r?\n/)) {
+    const m = lineRe.exec(line);
+    if (!m) continue;
+    const [, name, type, rawValue] = m;
+    if (!POLICY_KEYS.includes(name)) continue;
+    if (type === 'REG_DWORD' || type === 'REG_QWORD') {
+      out[name] = parseInt(rawValue, 16);
+    } else {
+      out[name] = rawValue;
+    }
+  }
+  return out;
+}
+
+/** `{ values, source }` for one registry hive, or `{ values: {}, source }`
+ *  on any failure (key absent — the normal "no policy set" case — missing
+ *  `reg` binary, or a platform that isn't Windows at all). Never throws:
+ *  an operator without IT policy must see the gateway behave exactly as it
+ *  always has.
+ *
+ *  `SUVEREN_POLICY_REGISTRY=off` skips the registry entirely, returning
+ *  `{}` without even spawning `reg` — unit tests set this globally (see
+ *  each app's vitest setup) so a real IT policy on the machine running the
+ *  suite, or another package's test writing to the registry concurrently,
+ *  cannot change what these tests see. Production never sets this. */
+function readRegistryHive(hive) {
+  const path = registryKeyPath(hive);
+  const source = `the registry policy (${path})`;
+  // Checked BEFORE the platform branch so the switch is testable on any OS,
+  // not just Windows — see gateway-policy.test.ts.
+  if (process.env.SUVEREN_POLICY_REGISTRY === 'off') return { values: {}, source };
+  if (process.platform !== 'win32') return { values: {}, source };
+  let result;
+  try {
+    result = spawnSync('reg', ['query', path], { encoding: 'utf8' });
+  } catch {
+    return { values: {}, source };
+  }
+  if (!result || result.status !== 0 || !result.stdout) return { values: {}, source };
+  return { values: parseRegQueryOutput(result.stdout), source };
+}
+
+// ─── Policy file ────────────────────────────────────────────────────────
+
+export function policyFilePath() {
+  if (process.env.SUVEREN_POLICY_FILE) return process.env.SUVEREN_POLICY_FILE;
+  if (process.platform === 'win32') {
+    const programData = process.env.ProgramData || process.env.PROGRAMDATA || 'C:\\ProgramData';
+    return join(programData, 'Suveren', 'gateway-policy.json');
+  }
+  if (process.platform === 'darwin') {
+    return '/Library/Application Support/Suveren/gateway-policy.json';
+  }
+  return '/etc/suveren/gateway-policy.json';
+}
+
+/** Throws (fail closed, audibly — same rule as config.mjs's
+ *  readConfigStrict) when the file exists but is not valid JSON. A missing
+ *  file is the normal "no policy set" case and returns `{}`. */
+function readPolicyFile() {
+  const path = policyFilePath();
+  const source = `the policy file (${path})`;
+  if (!existsSync(path)) return { values: {}, source };
+  let data;
+  try {
+    data = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    throw new Error(`Could not parse policy file ${path}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const values = {};
+  for (const key of POLICY_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(data, key)) values[key] = data[key];
+  }
+  return { values, source };
+}
+
+// ─── Merge + validate ───────────────────────────────────────────────────
+
+/** First entry (in precedence order) that defines each key wins. Returns
+ *  the merged raw values plus, per key, which source they came from (for
+ *  error messages). */
+function mergeBySource(entries) {
+  const merged = {};
+  const sourceOf = {};
+  for (const key of POLICY_KEYS) {
+    for (const entry of entries) {
+      if (Object.prototype.hasOwnProperty.call(entry.values, key) && entry.values[key] !== undefined) {
+        merged[key] = entry.values[key];
+        sourceOf[key] = entry.source;
+        break;
+      }
+    }
+  }
+  return { merged, sourceOf };
+}
+
+let cached = null;
+
+/**
+ * Read + validate the effective policy. Memoized for the life of the
+ * process (registry reads spawn a child process — doing that on every
+ * `isSimulationMode()` call, which runs per tool call, would be a
+ * synchronous fork on the hot path). Policy changes take effect on the next
+ * restart anyway, same as every other setting here — see
+ * `_resetPolicyCacheForTests` for the one case that needs otherwise.
+ *
+ * Throws a named error — mentioning the key, the offending value, and which
+ * source it came from — on an invalid value, exactly like a bad `config
+ * set` input (see config.mjs's resolveAsUrl doc comment on failing closed
+ * and audibly rather than silently falling back).
+ */
+export function readPolicy() {
+  if (cached) return cached;
+
+  const hklm = readRegistryHive('HKLM');
+  const hkcu = readRegistryHive('HKCU');
+  const file = readPolicyFile(); // may throw — propagated, not swallowed
+
+  const { merged, sourceOf } = mergeBySource([hklm, hkcu, file]);
+
+  const policy = {};
+  const locked = new Set();
+
+  if (merged.AsUrl !== undefined) {
+    const v = validateAsUrl(String(merged.AsUrl));
+    if (!v.ok) {
+      throw new Error(`Invalid policy AsUrl ("${merged.AsUrl}") from ${sourceOf.AsUrl}: ${v.error}`);
+    }
+    policy.asUrl = v.url;
+    locked.add('asUrl');
+  }
+
+  if (merged.CaFile !== undefined) {
+    const v = validateCaFile(String(merged.CaFile));
+    if (!v.ok) {
+      throw new Error(`Invalid policy CaFile ("${merged.CaFile}") from ${sourceOf.CaFile}: ${v.error}`);
+    }
+    policy.caFile = v.path;
+    locked.add('caFile');
+  }
+
+  if (merged.PinTls !== undefined) {
+    const b = coerceBoolean(merged.PinTls);
+    if (b === undefined) {
+      throw new Error(
+        `Invalid policy PinTls ("${merged.PinTls}") from ${sourceOf.PinTls}: must be a boolean or 0/1.`,
+      );
+    }
+    policy.pinTls = b;
+    locked.add('pinTls');
+  }
+
+  if (merged.Proxy !== undefined) {
+    const v = validateProxyUrl(String(merged.Proxy));
+    if (!v.ok) {
+      throw new Error(`Invalid policy Proxy ("${merged.Proxy}") from ${sourceOf.Proxy}: ${v.error}`);
+    }
+    policy.proxy = v.url;
+    locked.add('proxy');
+  }
+
+  // NoProxy has no saved-config/CLI counterpart — just a string, no URL
+  // shape to validate (it's a NO_PROXY-style hostname list, same grammar as
+  // the env var itself).
+  if (merged.NoProxy !== undefined) {
+    const raw = String(merged.NoProxy).trim();
+    if (!raw) {
+      throw new Error(`Invalid policy NoProxy ("${merged.NoProxy}") from ${sourceOf.NoProxy}: must not be empty.`);
+    }
+    policy.noProxy = raw;
+    locked.add('noProxy');
+  }
+
+  if (merged.Simulation !== undefined) {
+    const b = coerceBoolean(merged.Simulation);
+    if (b === undefined) {
+      throw new Error(
+        `Invalid policy Simulation ("${merged.Simulation}") from ${sourceOf.Simulation}: must be a boolean or 0/1.`,
+      );
+    }
+    policy.simulation = b;
+    locked.add('simulation');
+  }
+
+  if (merged.InstallMethod !== undefined) {
+    const raw = String(merged.InstallMethod).trim().toLowerCase();
+    if (raw !== 'managed') {
+      throw new Error(
+        `Invalid policy InstallMethod ("${merged.InstallMethod}") from ${sourceOf.InstallMethod}: only "managed" is supported.`,
+      );
+    }
+    policy.installMethod = 'managed';
+    locked.add('installMethod');
+  }
+
+  cached = { policy, locked };
+  return cached;
+}
+
+/** Convenience: is this one key locked by policy? */
+export function isPolicyLocked(key) {
+  return readPolicy().locked.has(key);
+}
+
+/** Drop the memoized policy so the next `readPolicy()` call re-reads the
+ *  registry/file. Test-only — a real process never needs this, since
+ *  policy is only ever consulted again after a restart. */
+export function _resetPolicyCacheForTests() {
+  cached = null;
+}

package/node_modules/@hap/core/dist/index.d.mts

@@ -205,10 +205,29 @@ type BoundType =
  * Per-transaction cap. The execution context field named in `of` must
  * satisfy `execution[of] <= bound` for the current call. No cumulative
  * tracking. Used by: amount_max, recipient_max, booking_duration_max, etc.
+ *
+ * `requiredFor` (v0.8+) closes the converse: without it, a call that does
+ * not carry `of` at all is simply skipped — a 5,000 cap refuses 6,000 but
+ * permits a call that declares no value whatsoever, which is indistinguishable
+ * from an unenforced bound. The same hole, and the same fix, as
+ * `FieldConstraint.requiredFor` on a scope constraint (below): values drawn
+ * from the profile's `boundsSchema.actionTypes` registry. For a listed
+ * `action_type`, an execution whose context lacks `of` — or whose value is
+ * not a finite number — MUST be refused rather than skipped. For an
+ * unlisted (or when `requiredFor` is absent) action type, today's
+ * skip-on-absence behaviour is unchanged. Meaningful only on
+ * `per_transaction`; the other `BoundType` kinds have no per-call "value
+ * exposed or not" question — `cumulative_sum`/`cumulative_count` always read
+ * from the execution log regardless of what this call declares, and `enum`
+ * is a capability flag, not a runtime value — so the field does not exist
+ * on those variants and a profile that puts it there has it silently
+ * ignored by every enforcement point (TypeScript also refuses it when the
+ * profile is authored against this type rather than raw JSON).
  */
 {
     kind: 'per_transaction';
     of: string;
+    requiredFor?: string[];
 }
 /**
  * Cumulative sum within a time window. The SP maintains a running sum
@@ -503,6 +522,16 @@ interface AgentProfile {
     boundsSchema?: {
         keyOrder: string[];
         fields: Record<string, ProfileBoundsField>;
+        /**
+         * v0.5+ registry of the action types this profile recognizes (e.g.
+         * `["send", "delete", "setup"]`). Every `execution.action_type` the
+         * Authority Server and gateway accept for this profile MUST be a member
+         * when the registry is declared (protocol.md → Bounds Schema, rule 2);
+         * it is also what a `per_transaction` bound's `requiredFor` draws from.
+         * Absent on profiles published before the registry existed — membership
+         * is then uncheckable, not a violation.
+         */
+        actionTypes?: readonly string[];
     };
     /**
      * v0.4 context schema — defines the execution context parameters (e.g., currency, action_type).
@@ -983,6 +1012,25 @@ declare function validateContextParams(params: AgentContextParams, profile: Agen
     valid: boolean;
     errors: string[];
 };
+/**
+ * Authoring-time check for `per_transaction` bound `requiredFor` (v0.8+):
+ * entries must name a real `action_type` from the profile's declared
+ * `boundsSchema.actionTypes` registry, and the field is only meaningful on
+ * `per_transaction` bounds (see `BoundType`'s doc comment for why the other
+ * kinds don't carry it).
+ *
+ * This is NOT wired into `registerProfile` or any enforcement path — nothing
+ * in hap-core validates profile JSON at load time today (the pre-existing
+ * `requiredFor` on a context/scope constraint has the same gap), so adding
+ * an automatic refusal here would be new behaviour beyond this change's
+ * scope. Call it explicitly from an authoring tool, a hap-profiles CI check,
+ * or a test, to catch a `requiredFor` entry that can never match (misspelled
+ * action type) or is attached to a bound kind that silently ignores it.
+ *
+ * Returns an empty array when the profile has no boundsSchema or nothing to
+ * check — never throws.
+ */
+declare function validateBoundsRequiredFor(profile: AgentProfile): string[];
 /**
  * Thrown when a value cannot be canonicalized at all — currently only for raw
  * LF/CR inside a value. Carries the protocol error code so callers can map it
@@ -1353,4 +1401,4 @@ interface ReceiptPayload {
  */
 declare function verifyReceiptSignature(receipt: ReceiptPayload, publicKeyHex: string): Promise<void>;
 
-export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type ApprovalObject, type Attestation, type AttestationHeader, type AttestationPayload, type BoundType, CanonicalValueError, type ContentBinding, ContentBindingError, type ContentBindingErrorCode, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type ExecutionMappingTransform, type ExecutionMappingValue, type ExecutionPath, type FieldConstraint, type FieldUnit, type GateQuestion, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, type MandateBinding, MandateError, type MandateProjection, type OwnerMandate, type ProfileBoundsField, type ProfileContextField, type ProfileFrameField, type ProfileToolGating, type ProfileToolGatingEntry, type ReceiptPayload, type ResolvedDomain, type SigningSurface, type Subject, type SubjectValidation, approvalSigningBytes, attestationId, bindingAppliesTo, boundActionTypes, buildMandateProjection, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFieldsContentHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, decodeDidKey, deriveIdentityLine, encodeAttestationBlob, encodeDidKey, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isFieldBinding, isKeyBearingDid, isV4Attestation, listProfiles, mandateSigningBytes, registerProfile, selectBoundFields, signApproval, signMandateProjection, validateBoundsParams, validateContextParams, validateFrameParams, validateSubject, verify, verifyApproval, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash, verifyOwnerMandate, verifyOwnerMandates, verifyReceiptSignature };
+export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type ApprovalObject, type Attestation, type AttestationHeader, type AttestationPayload, type BoundType, CanonicalValueError, type ContentBinding, ContentBindingError, type ContentBindingErrorCode, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type ExecutionMappingTransform, type ExecutionMappingValue, type ExecutionPath, type FieldConstraint, type FieldUnit, type GateQuestion, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, type MandateBinding, MandateError, type MandateProjection, type OwnerMandate, type ProfileBoundsField, type ProfileContextField, type ProfileFrameField, type ProfileToolGating, type ProfileToolGatingEntry, type ReceiptPayload, type ResolvedDomain, type SigningSurface, type Subject, type SubjectValidation, approvalSigningBytes, attestationId, bindingAppliesTo, boundActionTypes, buildMandateProjection, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFieldsContentHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, decodeDidKey, deriveIdentityLine, encodeAttestationBlob, encodeDidKey, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isFieldBinding, isKeyBearingDid, isV4Attestation, listProfiles, mandateSigningBytes, registerProfile, selectBoundFields, signApproval, signMandateProjection, validateBoundsParams, validateBoundsRequiredFor, validateContextParams, validateFrameParams, validateSubject, verify, verifyApproval, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash, verifyOwnerMandate, verifyOwnerMandates, verifyReceiptSignature };

package/node_modules/@hap/core/dist/index.d.ts

@@ -205,10 +205,29 @@ type BoundType =
  * Per-transaction cap. The execution context field named in `of` must
  * satisfy `execution[of] <= bound` for the current call. No cumulative
  * tracking. Used by: amount_max, recipient_max, booking_duration_max, etc.
+ *
+ * `requiredFor` (v0.8+) closes the converse: without it, a call that does
+ * not carry `of` at all is simply skipped — a 5,000 cap refuses 6,000 but
+ * permits a call that declares no value whatsoever, which is indistinguishable
+ * from an unenforced bound. The same hole, and the same fix, as
+ * `FieldConstraint.requiredFor` on a scope constraint (below): values drawn
+ * from the profile's `boundsSchema.actionTypes` registry. For a listed
+ * `action_type`, an execution whose context lacks `of` — or whose value is
+ * not a finite number — MUST be refused rather than skipped. For an
+ * unlisted (or when `requiredFor` is absent) action type, today's
+ * skip-on-absence behaviour is unchanged. Meaningful only on
+ * `per_transaction`; the other `BoundType` kinds have no per-call "value
+ * exposed or not" question — `cumulative_sum`/`cumulative_count` always read
+ * from the execution log regardless of what this call declares, and `enum`
+ * is a capability flag, not a runtime value — so the field does not exist
+ * on those variants and a profile that puts it there has it silently
+ * ignored by every enforcement point (TypeScript also refuses it when the
+ * profile is authored against this type rather than raw JSON).
  */
 {
     kind: 'per_transaction';
     of: string;
+    requiredFor?: string[];
 }
 /**
  * Cumulative sum within a time window. The SP maintains a running sum
@@ -503,6 +522,16 @@ interface AgentProfile {
     boundsSchema?: {
         keyOrder: string[];
         fields: Record<string, ProfileBoundsField>;
+        /**
+         * v0.5+ registry of the action types this profile recognizes (e.g.
+         * `["send", "delete", "setup"]`). Every `execution.action_type` the
+         * Authority Server and gateway accept for this profile MUST be a member
+         * when the registry is declared (protocol.md → Bounds Schema, rule 2);
+         * it is also what a `per_transaction` bound's `requiredFor` draws from.
+         * Absent on profiles published before the registry existed — membership
+         * is then uncheckable, not a violation.
+         */
+        actionTypes?: readonly string[];
     };
     /**
      * v0.4 context schema — defines the execution context parameters (e.g., currency, action_type).
@@ -983,6 +1012,25 @@ declare function validateContextParams(params: AgentContextParams, profile: Agen
     valid: boolean;
     errors: string[];
 };
+/**
+ * Authoring-time check for `per_transaction` bound `requiredFor` (v0.8+):
+ * entries must name a real `action_type` from the profile's declared
+ * `boundsSchema.actionTypes` registry, and the field is only meaningful on
+ * `per_transaction` bounds (see `BoundType`'s doc comment for why the other
+ * kinds don't carry it).
+ *
+ * This is NOT wired into `registerProfile` or any enforcement path — nothing
+ * in hap-core validates profile JSON at load time today (the pre-existing
+ * `requiredFor` on a context/scope constraint has the same gap), so adding
+ * an automatic refusal here would be new behaviour beyond this change's
+ * scope. Call it explicitly from an authoring tool, a hap-profiles CI check,
+ * or a test, to catch a `requiredFor` entry that can never match (misspelled
+ * action type) or is attached to a bound kind that silently ignores it.
+ *
+ * Returns an empty array when the profile has no boundsSchema or nothing to
+ * check — never throws.
+ */
+declare function validateBoundsRequiredFor(profile: AgentProfile): string[];
 /**
  * Thrown when a value cannot be canonicalized at all — currently only for raw
  * LF/CR inside a value. Carries the protocol error code so callers can map it
@@ -1353,4 +1401,4 @@ interface ReceiptPayload {
  */
 declare function verifyReceiptSignature(receipt: ReceiptPayload, publicKeyHex: string): Promise<void>;
 
-export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type ApprovalObject, type Attestation, type AttestationHeader, type AttestationPayload, type BoundType, CanonicalValueError, type ContentBinding, ContentBindingError, type ContentBindingErrorCode, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type ExecutionMappingTransform, type ExecutionMappingValue, type ExecutionPath, type FieldConstraint, type FieldUnit, type GateQuestion, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, type MandateBinding, MandateError, type MandateProjection, type OwnerMandate, type ProfileBoundsField, type ProfileContextField, type ProfileFrameField, type ProfileToolGating, type ProfileToolGatingEntry, type ReceiptPayload, type ResolvedDomain, type SigningSurface, type Subject, type SubjectValidation, approvalSigningBytes, attestationId, bindingAppliesTo, boundActionTypes, buildMandateProjection, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFieldsContentHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, decodeDidKey, deriveIdentityLine, encodeAttestationBlob, encodeDidKey, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isFieldBinding, isKeyBearingDid, isV4Attestation, listProfiles, mandateSigningBytes, registerProfile, selectBoundFields, signApproval, signMandateProjection, validateBoundsParams, validateContextParams, validateFrameParams, validateSubject, verify, verifyApproval, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash, verifyOwnerMandate, verifyOwnerMandates, verifyReceiptSignature };
+export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type ApprovalObject, type Attestation, type AttestationHeader, type AttestationPayload, type BoundType, CanonicalValueError, type ContentBinding, ContentBindingError, type ContentBindingErrorCode, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type ExecutionMappingTransform, type ExecutionMappingValue, type ExecutionPath, type FieldConstraint, type FieldUnit, type GateQuestion, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, type MandateBinding, MandateError, type MandateProjection, type OwnerMandate, type ProfileBoundsField, type ProfileContextField, type ProfileFrameField, type ProfileToolGating, type ProfileToolGatingEntry, type ReceiptPayload, type ResolvedDomain, type SigningSurface, type Subject, type SubjectValidation, approvalSigningBytes, attestationId, bindingAppliesTo, boundActionTypes, buildMandateProjection, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFieldsContentHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, decodeDidKey, deriveIdentityLine, encodeAttestationBlob, encodeDidKey, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isFieldBinding, isKeyBearingDid, isV4Attestation, listProfiles, mandateSigningBytes, registerProfile, selectBoundFields, signApproval, signMandateProjection, validateBoundsParams, validateBoundsRequiredFor, validateContextParams, validateFrameParams, validateSubject, verify, verifyApproval, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash, verifyOwnerMandate, verifyOwnerMandates, verifyReceiptSignature };

package/node_modules/@hap/core/dist/index.js

@@ -72,6 +72,7 @@ __export(index_exports, {
   signApproval: () => signApproval,
   signMandateProjection: () => signMandateProjection,
   validateBoundsParams: () => validateBoundsParams,
+  validateBoundsRequiredFor: () => validateBoundsRequiredFor,
   validateContextParams: () => validateContextParams,
   validateFrameParams: () => validateFrameParams,
   validateSubject: () => validateSubject,
@@ -378,6 +379,38 @@ function validateContextParams(params, profile) {
   }
   return { valid: errors.length === 0, errors };
 }
+function validateBoundsRequiredFor(profile) {
+  const errors = [];
+  const boundsSchema = profile.boundsSchema;
+  if (!boundsSchema) return errors;
+  const actionTypes = boundsSchema.actionTypes ? [...boundsSchema.actionTypes] : void 0;
+  for (const [fieldName, fieldDef] of Object.entries(boundsSchema.fields)) {
+    const bt = fieldDef.boundType;
+    if (!bt) continue;
+    const requiredFor = bt.requiredFor;
+    if (requiredFor === void 0) continue;
+    if (!Array.isArray(requiredFor) || !requiredFor.every((v) => typeof v === "string")) {
+      errors.push(`Bound "${fieldName}": requiredFor must be a string array.`);
+      continue;
+    }
+    if (bt.kind !== "per_transaction") {
+      errors.push(
+        `Bound "${fieldName}": requiredFor is only meaningful on a per_transaction bound (found on kind "${bt.kind}") \u2014 every enforcement point ignores it there. Remove it.`
+      );
+      continue;
+    }
+    if (actionTypes) {
+      for (const actionType of requiredFor) {
+        if (!actionTypes.includes(actionType)) {
+          errors.push(
+            `Bound "${fieldName}": requiredFor names action type "${actionType}", which is not in this profile's boundsSchema.actionTypes registry [${actionTypes.join(", ")}]. It can never match a real execution and the requirement is dead.`
+          );
+        }
+      }
+    }
+  }
+  return errors;
+}
 var CanonicalValueError = class extends Error {
   code;
   field;
@@ -820,6 +853,22 @@ function checkBoundsV4(request, profile, executionLog, now) {
     switch (bt.kind) {
       case "per_transaction": {
         const actual = request.execution[bt.of];
+        const engaged = !!bt.requiredFor?.length && actionType !== void 0 && bt.requiredFor.includes(actionType);
+        if (engaged) {
+          const missing = actual === void 0 || actual === null;
+          const numericActual = missing ? NaN : typeof actual === "number" ? actual : Number(actual);
+          const missingOrNonNumeric = missing || Number.isNaN(numericActual);
+          if (missingOrNonNumeric) {
+            errors.push({
+              code: "BOUND_EXCEEDED",
+              field: bt.of,
+              message: missing ? `Bound "${fieldName}" requires "${bt.of}" for "${actionType}" calls, but this call exposes no ${bt.of} to check against it. Refusing: the call cannot be shown to stay within ${fieldName}.` : `Bound "${fieldName}" requires a numeric "${bt.of}" for "${actionType}" calls, but this call's value (${String(actual)}) is not a number. Refusing: the call cannot be shown to stay within ${fieldName}.`,
+              bound: boundValue,
+              actual
+            });
+            continue;
+          }
+        }
         if (actual === void 0) continue;
         if (typeof boundValue !== "number" || typeof actual !== "number") {
           errors.push({
@@ -1266,6 +1315,7 @@ async function verifyReceiptSignature(receipt, publicKeyHex) {
   signApproval,
   signMandateProjection,
   validateBoundsParams,
+  validateBoundsRequiredFor,
   validateContextParams,
   validateFrameParams,
   validateSubject,