@humanagencyp/hap-core 0.6.2 → 0.8.0

package/dist/index.d.mts

@@ -113,6 +113,27 @@ interface Attestation {
 interface FieldConstraint {
     type: 'number' | 'string';
     enforceable: Array<'max' | 'enum' | 'subset'>;
+    /**
+     * Action types for which this dimension MUST be present in the execution
+     * context. When the grant constrains this field and the action is one of
+     * these, an absent value is a denial rather than a skipped check.
+     *
+     * Without it, a constraint is only enforced against calls that happen to
+     * expose the value. Gmail's `send_message` is the live case: pass `raw` and
+     * `to` is never populated, so `allowed_recipients` had nothing to compare and
+     * the check passed — a send to an unverified recipient looked authorized.
+     * `send_draft` has the same shape: it transmits, and the Gatekeeper cannot
+     * see to whom.
+     *
+     * Keyed on `action_type` because "does this action engage recipients?" is a
+     * property of the action, not of the field name — deleting a draft has no
+     * recipients and must keep passing, while sending one must not. This keeps
+     * the engine profile-agnostic: it compares declared strings and knows nothing
+     * about email, calendars or payments.
+     *
+     * Omitted → previous behaviour: absence skips the check.
+     */
+    requiredFor?: string[];
 }
 /**
  * Frame field definition within a profile.
@@ -210,6 +231,21 @@ interface ProfileBoundsField {
      * treat a missing boundType as an error when running in v0.4 mode.
      */
     boundType?: BoundType;
+    /**
+     * Which execution action types this bound governs, e.g. `["write"]`.
+     *
+     * When present, this is authoritative. When absent, enforcement falls back to
+     * inferring the action type from the FIELD NAME (`send_daily_max` → `send`),
+     * which is a convention rather than a contract: a profile that names a bound
+     * after the domain concept instead of the action — calendar's
+     * `booking_daily_max` against an action type of `write` — matches nothing and
+     * is skipped, so a limit the user set is never applied and nothing says so.
+     *
+     * Declaring it removes the guess. Deliberately additive: profiles migrate one
+     * at a time, and every remaining fallback is logged, so the cases still
+     * relying on the naming convention become visible instead of staying silent.
+     */
+    appliesTo?: string[];
     /**
      * The measurement dimension of the bound's value. UI renders the unit
      * inline next to the input (e.g. `4 min`, `100 EUR`). Independent from
@@ -474,6 +510,18 @@ interface GatekeeperRequest {
     execution: Record<string, string | number>;
     /** v0.4: context parameters (currency, action_type, etc.) */
     context?: AgentContextParams;
+    /**
+     * Authorization path used to scope cumulative lookups in the execution log.
+     *
+     * Deliberately OUTSIDE `frame`: the frame is hashed and validated against the
+     * profile's boundsSchema, so an extra key there is rejected as an unknown
+     * field and breaks attestation verification outright. Cumulative checks
+     * previously read the path from the frame, where callers cannot legally put
+     * it — so it resolved to "" while the log stored real paths, no entry ever
+     * matched, and every running total read zero. The local gate existed but
+     * could never fire.
+     */
+    path?: string;
 }
 /**
  * Structured error from Gatekeeper verification.

package/dist/index.d.ts

@@ -113,6 +113,27 @@ interface Attestation {
 interface FieldConstraint {
     type: 'number' | 'string';
     enforceable: Array<'max' | 'enum' | 'subset'>;
+    /**
+     * Action types for which this dimension MUST be present in the execution
+     * context. When the grant constrains this field and the action is one of
+     * these, an absent value is a denial rather than a skipped check.
+     *
+     * Without it, a constraint is only enforced against calls that happen to
+     * expose the value. Gmail's `send_message` is the live case: pass `raw` and
+     * `to` is never populated, so `allowed_recipients` had nothing to compare and
+     * the check passed — a send to an unverified recipient looked authorized.
+     * `send_draft` has the same shape: it transmits, and the Gatekeeper cannot
+     * see to whom.
+     *
+     * Keyed on `action_type` because "does this action engage recipients?" is a
+     * property of the action, not of the field name — deleting a draft has no
+     * recipients and must keep passing, while sending one must not. This keeps
+     * the engine profile-agnostic: it compares declared strings and knows nothing
+     * about email, calendars or payments.
+     *
+     * Omitted → previous behaviour: absence skips the check.
+     */
+    requiredFor?: string[];
 }
 /**
  * Frame field definition within a profile.
@@ -210,6 +231,21 @@ interface ProfileBoundsField {
      * treat a missing boundType as an error when running in v0.4 mode.
      */
     boundType?: BoundType;
+    /**
+     * Which execution action types this bound governs, e.g. `["write"]`.
+     *
+     * When present, this is authoritative. When absent, enforcement falls back to
+     * inferring the action type from the FIELD NAME (`send_daily_max` → `send`),
+     * which is a convention rather than a contract: a profile that names a bound
+     * after the domain concept instead of the action — calendar's
+     * `booking_daily_max` against an action type of `write` — matches nothing and
+     * is skipped, so a limit the user set is never applied and nothing says so.
+     *
+     * Declaring it removes the guess. Deliberately additive: profiles migrate one
+     * at a time, and every remaining fallback is logged, so the cases still
+     * relying on the naming convention become visible instead of staying silent.
+     */
+    appliesTo?: string[];
     /**
      * The measurement dimension of the bound's value. UI renders the unit
      * inline next to the input (e.g. `4 min`, `100 EUR`). Independent from
@@ -474,6 +510,18 @@ interface GatekeeperRequest {
     execution: Record<string, string | number>;
     /** v0.4: context parameters (currency, action_type, etc.) */
     context?: AgentContextParams;
+    /**
+     * Authorization path used to scope cumulative lookups in the execution log.
+     *
+     * Deliberately OUTSIDE `frame`: the frame is hashed and validated against the
+     * profile's boundsSchema, so an extra key there is rejected as an unknown
+     * field and breaks attestation verification outright. Cumulative checks
+     * previously read the path from the frame, where callers cannot legally put
+     * it — so it resolved to "" while the log stored real paths, no entry ever
+     * matched, and every running total read zero. The local gate existed but
+     * could never fire.
+     */
+    path?: string;
 }
 /**
  * Structured error from Gatekeeper verification.

package/dist/index.js

@@ -626,12 +626,23 @@ function checkBoundsFromFrameSchema(request, profile) {
   }
   return errors;
 }
+function boundGovernsAction(fieldName, fieldDef, bt, actionType) {
+  if (fieldDef.appliesTo) {
+    return actionType ? fieldDef.appliesTo.includes(actionType) : true;
+  }
+  if (bt.kind !== "cumulative_count" || !actionType) return true;
+  const prefix = fieldName.replace(/_(?:daily|monthly|weekly)_max$/, "");
+  const namedForAnAction = prefix !== fieldName;
+  const matches = prefix === actionType || prefix.startsWith("transaction");
+  return !namedForAnAction || matches;
+}
 function checkBoundsV4(request, profile, executionLog, now) {
   const errors = [];
   if (!profile.boundsSchema) return errors;
   const bounds = request.frame;
   const profileId = String(bounds.profile ?? profile.id);
-  const path = bounds.path ? String(bounds.path) : "";
+  const actionType = typeof request.execution.action_type === "string" ? request.execution.action_type : void 0;
+  const path = request.path ?? (bounds.path ? String(bounds.path) : "");
   for (const [fieldName, fieldDef] of Object.entries(profile.boundsSchema.fields)) {
     if (fieldName === "profile" || fieldName === "path") continue;
     const boundValue = bounds[fieldName];
@@ -647,6 +658,7 @@ function checkBoundsV4(request, profile, executionLog, now) {
       });
       continue;
     }
+    if (!boundGovernsAction(fieldName, fieldDef, bt, actionType)) continue;
     switch (bt.kind) {
       case "per_transaction": {
         const actual = request.execution[bt.of];
@@ -745,6 +757,23 @@ function checkContextConstraints(context, execution, profile) {
   if (!profile.contextSchema) return errors;
   for (const [fieldName, fieldDef] of Object.entries(profile.contextSchema.fields)) {
     if (!fieldDef.constraint) continue;
+    const requiredFor = fieldDef.constraint.requiredFor;
+    if (requiredFor?.length) {
+      const boundValue = context[fieldName];
+      const actualValue = execution[fieldName];
+      const actionType = execution["action_type"];
+      const constrained = boundValue !== void 0 && boundValue !== "";
+      const engaged = actionType !== void 0 && requiredFor.includes(String(actionType));
+      if (constrained && engaged && (actualValue === void 0 || actualValue === "")) {
+        errors.push({
+          code: "BOUND_EXCEEDED",
+          field: fieldName,
+          message: `Authorization limits "${fieldName}" to [${boundValue}], but this "${String(actionType)}" call exposes no ${fieldName} to check against it. Refusing: the call cannot be shown to stay in scope.`,
+          bound: boundValue
+        });
+        continue;
+      }
+    }
     for (const enforceType of fieldDef.constraint.enforceable) {
       if (enforceType === "enum") {
         const boundValue = context[fieldName];

package/dist/index.mjs

@@ -555,12 +555,23 @@ function checkBoundsFromFrameSchema(request, profile) {
   }
   return errors;
 }
+function boundGovernsAction(fieldName, fieldDef, bt, actionType) {
+  if (fieldDef.appliesTo) {
+    return actionType ? fieldDef.appliesTo.includes(actionType) : true;
+  }
+  if (bt.kind !== "cumulative_count" || !actionType) return true;
+  const prefix = fieldName.replace(/_(?:daily|monthly|weekly)_max$/, "");
+  const namedForAnAction = prefix !== fieldName;
+  const matches = prefix === actionType || prefix.startsWith("transaction");
+  return !namedForAnAction || matches;
+}
 function checkBoundsV4(request, profile, executionLog, now) {
   const errors = [];
   if (!profile.boundsSchema) return errors;
   const bounds = request.frame;
   const profileId = String(bounds.profile ?? profile.id);
-  const path = bounds.path ? String(bounds.path) : "";
+  const actionType = typeof request.execution.action_type === "string" ? request.execution.action_type : void 0;
+  const path = request.path ?? (bounds.path ? String(bounds.path) : "");
   for (const [fieldName, fieldDef] of Object.entries(profile.boundsSchema.fields)) {
     if (fieldName === "profile" || fieldName === "path") continue;
     const boundValue = bounds[fieldName];
@@ -576,6 +587,7 @@ function checkBoundsV4(request, profile, executionLog, now) {
       });
       continue;
     }
+    if (!boundGovernsAction(fieldName, fieldDef, bt, actionType)) continue;
     switch (bt.kind) {
       case "per_transaction": {
         const actual = request.execution[bt.of];
@@ -674,6 +686,23 @@ function checkContextConstraints(context, execution, profile) {
   if (!profile.contextSchema) return errors;
   for (const [fieldName, fieldDef] of Object.entries(profile.contextSchema.fields)) {
     if (!fieldDef.constraint) continue;
+    const requiredFor = fieldDef.constraint.requiredFor;
+    if (requiredFor?.length) {
+      const boundValue = context[fieldName];
+      const actualValue = execution[fieldName];
+      const actionType = execution["action_type"];
+      const constrained = boundValue !== void 0 && boundValue !== "";
+      const engaged = actionType !== void 0 && requiredFor.includes(String(actionType));
+      if (constrained && engaged && (actualValue === void 0 || actualValue === "")) {
+        errors.push({
+          code: "BOUND_EXCEEDED",
+          field: fieldName,
+          message: `Authorization limits "${fieldName}" to [${boundValue}], but this "${String(actionType)}" call exposes no ${fieldName} to check against it. Refusing: the call cannot be shown to stay in scope.`,
+          bound: boundValue
+        });
+        continue;
+      }
+    }
     for (const enforceType of fieldDef.constraint.enforceable) {
       if (enforceType === "enum") {
         const boundValue = context[fieldName];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanagencyp/hap-core",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "Core types, cryptographic primitives, and verification logic for the Human Agency Protocol",
   "license": "MIT",
   "repository": {

package/src/gatekeeper.ts

@@ -40,6 +40,8 @@ import type {
   AgentContextParams,
   ExecutionLogQuery,
   CumulativeFieldDef,
+  ProfileBoundsField,
+  BoundType,
 } from './types';
 
 /**
@@ -406,6 +408,41 @@ function checkBoundsFromFrameSchema(request: GatekeeperRequest, profile: AgentPr
  *   enum             — bound value must be in the allowed set (attest-time
  *                      validation; not an execution-time check)
  */
+/**
+ * Does this bound govern the action being attempted?
+ *
+ * Cumulative totals are scoped by (profileId, path) only, so without this every
+ * cumulative_count bound on a profile sees the same running count. On customers
+ * — which declares both write_daily_max and delete_daily_max — the smaller
+ * delete limit would count writes and block them.
+ *
+ * Preferred answer is the profile's declared `appliesTo`. Absent that, fall back
+ * to the field-name convention (`delete_daily_max` → `delete`), matching how the
+ * Authority Server selects bounds so the two enforcement points cannot disagree.
+ *
+ * Fails CLOSED: when the action type is unknown, or the bound's name implies no
+ * particular action, the bound is enforced.
+ */
+function boundGovernsAction(
+  fieldName: string,
+  fieldDef: ProfileBoundsField,
+  bt: BoundType,
+  actionType: string | undefined,
+): boolean {
+  if (fieldDef.appliesTo) {
+    return actionType ? fieldDef.appliesTo.includes(actionType) : true;
+  }
+
+  // The name convention only ever disambiguated count bounds; sums are governed
+  // by their `of` field and stay unfiltered, as at the Authority Server.
+  if (bt.kind !== 'cumulative_count' || !actionType) return true;
+
+  const prefix = fieldName.replace(/_(?:daily|monthly|weekly)_max$/, '');
+  const namedForAnAction = prefix !== fieldName;
+  const matches = prefix === actionType || prefix.startsWith('transaction');
+  return !namedForAnAction || matches;
+}
+
 function checkBoundsV4(
   request: GatekeeperRequest,
   profile: AgentProfile,
@@ -417,7 +454,14 @@ function checkBoundsV4(
 
   const bounds = request.frame as AgentBoundsParams;
   const profileId = String(bounds.profile ?? profile.id);
-  const path = bounds.path ? String(bounds.path) : '';
+  const actionType = typeof request.execution.action_type === 'string'
+    ? request.execution.action_type
+    : undefined;
+  // Prefer the explicit request path. `frame.path` is retained only as a
+  // fallback for callers that legitimately declare `path` in their profile's
+  // boundsSchema; for every shipped profile it is absent, which is exactly why
+  // this silently resolved to "" and disabled the cumulative gate entirely.
+  const path = request.path ?? (bounds.path ? String(bounds.path) : '');
 
   for (const [fieldName, fieldDef] of Object.entries(profile.boundsSchema.fields)) {
     if (fieldName === 'profile' || fieldName === 'path') continue;
@@ -441,6 +485,8 @@ function checkBoundsV4(
       continue;
     }
 
+    if (!boundGovernsAction(fieldName, fieldDef, bt, actionType)) continue;
+
     switch (bt.kind) {
       case 'per_transaction': {
         const actual = request.execution[bt.of];
@@ -566,6 +612,34 @@ function checkContextConstraints(
   for (const [fieldName, fieldDef] of Object.entries(profile.contextSchema.fields)) {
     if (!fieldDef.constraint) continue;
 
+    // A constrained dimension that the call does not expose cannot be checked.
+    // Skipping is only safe when the action does not engage that dimension —
+    // deleting a draft has no recipients. When it DOES engage it, silence must
+    // not read as compliance: an absent value means the Gatekeeper cannot show
+    // the call is in scope, and an unverifiable send is exactly what the scope
+    // exists to prevent. The profile declares which actions engage the field.
+    const requiredFor = fieldDef.constraint.requiredFor;
+    if (requiredFor?.length) {
+      const boundValue = context[fieldName];
+      const actualValue = execution[fieldName];
+      const actionType = execution['action_type'];
+      const constrained = boundValue !== undefined && boundValue !== '';
+      const engaged = actionType !== undefined && requiredFor.includes(String(actionType));
+
+      if (constrained && engaged && (actualValue === undefined || actualValue === '')) {
+        errors.push({
+          code: 'BOUND_EXCEEDED',
+          field: fieldName,
+          message:
+            `Authorization limits "${fieldName}" to [${boundValue}], but this ` +
+            `"${String(actionType)}" call exposes no ${fieldName} to check against it. ` +
+            `Refusing: the call cannot be shown to stay in scope.`,
+          bound: boundValue,
+        });
+        continue; // nothing further to compare for this field
+      }
+    }
+
     for (const enforceType of fieldDef.constraint.enforceable) {
       if (enforceType === 'enum') {
         // The context field value is the allowed value; execution must match

package/src/types.ts

@@ -121,6 +121,27 @@ export interface Attestation {
 export interface FieldConstraint {
   type: 'number' | 'string';
   enforceable: Array<'max' | 'enum' | 'subset'>;
+  /**
+   * Action types for which this dimension MUST be present in the execution
+   * context. When the grant constrains this field and the action is one of
+   * these, an absent value is a denial rather than a skipped check.
+   *
+   * Without it, a constraint is only enforced against calls that happen to
+   * expose the value. Gmail's `send_message` is the live case: pass `raw` and
+   * `to` is never populated, so `allowed_recipients` had nothing to compare and
+   * the check passed — a send to an unverified recipient looked authorized.
+   * `send_draft` has the same shape: it transmits, and the Gatekeeper cannot
+   * see to whom.
+   *
+   * Keyed on `action_type` because "does this action engage recipients?" is a
+   * property of the action, not of the field name — deleting a draft has no
+   * recipients and must keep passing, while sending one must not. This keeps
+   * the engine profile-agnostic: it compares declared strings and knows nothing
+   * about email, calendars or payments.
+   *
+   * Omitted → previous behaviour: absence skips the check.
+   */
+  requiredFor?: string[];
 }
 
 /**
@@ -213,6 +234,21 @@ export interface ProfileBoundsField {
    * treat a missing boundType as an error when running in v0.4 mode.
    */
   boundType?: BoundType;
+  /**
+   * Which execution action types this bound governs, e.g. `["write"]`.
+   *
+   * When present, this is authoritative. When absent, enforcement falls back to
+   * inferring the action type from the FIELD NAME (`send_daily_max` → `send`),
+   * which is a convention rather than a contract: a profile that names a bound
+   * after the domain concept instead of the action — calendar's
+   * `booking_daily_max` against an action type of `write` — matches nothing and
+   * is skipped, so a limit the user set is never applied and nothing says so.
+   *
+   * Declaring it removes the guess. Deliberately additive: profiles migrate one
+   * at a time, and every remaining fallback is logged, so the cases still
+   * relying on the naming convention become visible instead of staying silent.
+   */
+  appliesTo?: string[];
   /**
    * The measurement dimension of the bound's value. UI renders the unit
    * inline next to the input (e.g. `4 min`, `100 EUR`). Independent from
@@ -502,6 +538,18 @@ export interface GatekeeperRequest {
   execution: Record<string, string | number>;
   /** v0.4: context parameters (currency, action_type, etc.) */
   context?: AgentContextParams;
+  /**
+   * Authorization path used to scope cumulative lookups in the execution log.
+   *
+   * Deliberately OUTSIDE `frame`: the frame is hashed and validated against the
+   * profile's boundsSchema, so an extra key there is rejected as an unknown
+   * field and breaks attestation verification outright. Cumulative checks
+   * previously read the path from the frame, where callers cannot legally put
+   * it — so it resolved to "" while the log stored real paths, no entry ever
+   * matched, and every running total read zero. The local gate existed but
+   * could never fire.
+   */
+  path?: string;
 }
 
 /**