@suveren/gateway 0.19.5 → 0.20.1

package/node_modules/@hap/core/package.json

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

package/node_modules/@hap/core/src/base64url.ts

@@ -0,0 +1,39 @@
+/**
+ * base64url (RFC 4648 §5), strict — no padding, no standard-base64 characters.
+ *
+ * protocol.md → *Mandate Payload* rule 3: "Signatures MUST be encoded as
+ * base64url without padding ... Implementations MUST NOT use standard base64
+ * (which differs in `+`/`/` vs `-`/`_` and in padding) — third-party verifiers
+ * reading the spec literally will reject standard-base64 signatures."
+ *
+ * Earlier hap-core verifiers were lenient: they translated `+`/`/` back from
+ * `-`/`_` and re-added padding before decoding, so a standard-base64 signature
+ * verified exactly as well as a base64url one — silently accepting the wire
+ * format the spec forbids. v0.7 closes that: decoding a string that is not
+ * strict base64url throws, never silently repairs it.
+ */
+
+const STRICT_B64URL = /^[A-Za-z0-9_-]*$/;
+
+/** Encode bytes as base64url with no padding. */
+export function toBase64Url(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/**
+ * Decode a STRICT base64url string (no padding, no `+`/`/`/`=`).
+ *
+ * @throws Error (no protocol code — the caller knows which artifact it was
+ * decoding and assigns the code) when the input carries a `+`, `/`, `=`, or
+ * any other byte outside the base64url alphabet.
+ */
+export function fromBase64Url(s: string): Uint8Array {
+  if (!STRICT_B64URL.test(s)) {
+    throw new Error(
+      `${JSON.stringify(s)} is not strict base64url — standard base64 ` +
+        '("+"/"/"/padding) is retired (protocol.md → Mandate Payload, rule 3).',
+    );
+  }
+  const padding = s.length % 4 === 0 ? '' : '='.repeat(4 - (s.length % 4));
+  return new Uint8Array(Buffer.from(s + padding, 'base64'));
+}

package/node_modules/@hap/core/src/commitment-modes.ts

@@ -28,24 +28,3 @@ export function allowedCommitmentModes(profile: AgentProfile): readonly Signable
 export function isCommitmentModeAllowed(profile: AgentProfile, mode: string): boolean {
   return isSignable(mode) && allowedCommitmentModes(profile).includes(mode);
 }
-
-/**
- * Authoring check for a profile's `commitment_modes` declaration — for
- * hap-profiles CI, an authoring tool or a test. Like `validateBoundsRequiredFor`
- * it is not wired into profile loading; enforcement reads the declaration
- * fail-closed through `allowedCommitmentModes`. Empty array = nothing to fix.
- */
-export function validateCommitmentModes(profile: AgentProfile): string[] {
-  const declared = (profile as { commitment_modes?: unknown }).commitment_modes;
-  if (declared === undefined) return [];
-  if (!Array.isArray(declared)) return ['commitment_modes must be a list of modes.'];
-  const errors: string[] = [];
-  if (declared.length === 0) errors.push('commitment_modes is empty — no mandate could ever be signed under this profile.');
-  const seen = new Set<unknown>();
-  for (const m of declared) {
-    if (!isSignable(m)) errors.push(`commitment_modes: "${String(m)}" is not a mode a signer can choose (${SIGNABLE_COMMITMENT_MODES.join(', ')}).`);
-    if (seen.has(m)) errors.push(`commitment_modes: "${String(m)}" appears twice.`);
-    seen.add(m);
-  }
-  return errors;
-}

package/node_modules/@hap/core/src/errors.ts

@@ -0,0 +1,76 @@
+/**
+ * Canonical v0.7 error codes — protocol.md → *Error Codes*.
+ *
+ * "Error codes are canonical across the protocol. Implementations MUST emit
+ * exactly these codes and MUST NOT alias them under different names." This
+ * module is the single list both the Gatekeeper (local checks) and any AS
+ * client built on this library read from, so the two cannot drift.
+ *
+ * v0.7 renamed every code that carried a retired word (attestation → mandate,
+ * context → scope, receipt → ticket) — see protocol.md → *Migration from
+ * v0.6* → "Error-code renames" for the old→new map. There is no alias: a v0.6
+ * code name is simply gone from this list, by design (no backward
+ * compatibility — CLAUDE.md "Decided by the owner").
+ */
+
+/** Codes an Authority Server (or a local Gatekeeper check) emits refusing a mandate request. */
+export const MANDATE_ERROR_CODES = [
+  'BOUNDS_HASH_MISMATCH',
+  'SCOPE_HASH_MISMATCH',
+  'INVALID_SIGNATURE',
+  'OWNER_NOT_COVERED',
+  'TTL_EXPIRED',
+  'PROFILE_NOT_FOUND',
+  'PROFILE_INVALID',
+  'PROFILE_HASH_MISMATCH',
+  'COVERAGE_INSUFFICIENT',
+  'MALFORMED_MANDATE',
+  'VERSION_UNSUPPORTED',
+  'OWNER_NOT_APPROVER',
+  'BOUNDS_INVALID_VALUE',
+  'SCOPE_INVALID_VALUE',
+  'ABOVE_CAP_CONFIG_INVALID',
+  'OWNER_SIGNATURE_REQUIRED',
+  'OWNER_SIGNATURE_INVALID',
+] as const;
+
+/** Codes an Authority Server emits refusing a ticket request. */
+export const TICKET_ERROR_CODES = [
+  'MANDATE_NOT_FOUND',
+  'MANDATE_EXPIRED',
+  'MANDATE_REVOKED',
+  'BOUND_EXCEEDED',
+  'CUMULATIVE_LIMIT_EXCEEDED',
+  'COVERAGE_INSUFFICIENT',
+  'PROFILE_NOT_FOUND',
+  'INVALID_ACTION_TYPE',
+  'APPROVAL_REQUIRED',
+  'PROPOSAL_REQUIRED',
+  'PROPOSAL_NOT_FOUND',
+  'PROPOSAL_NOT_APPROVED',
+  'PROPOSAL_EXPIRED',
+  'PROPOSAL_REJECTED',
+  'PROPOSAL_MISMATCH',
+  'PROPOSAL_MANDATE_MISMATCH',
+  'PROPOSAL_ALREADY_EXECUTED',
+  'MALFORMED_TICKET_REQUEST',
+  'IDEMPOTENCY_KEY_REQUIRED',
+  'IDEMPOTENCY_MISMATCH',
+  'APPROVAL_SIGNATURE_REQUIRED',
+  'APPROVAL_SIGNATURE_INVALID',
+] as const;
+
+/** The full canonical surface — every code a conformant implementation may emit. */
+export type HapErrorCode = (typeof MANDATE_ERROR_CODES)[number] | (typeof TICKET_ERROR_CODES)[number];
+
+/**
+ * A refusal carrying one of the canonical codes above. Thrown by local
+ * (Gatekeeper-side, no-wire-round-trip) checks in this library; an AS client
+ * built on hap-core maps a wire `{ code, message }` error onto the same type.
+ */
+export class HapError extends Error {
+  constructor(public readonly code: HapErrorCode, message: string) {
+    super(`${code}: ${message}`);
+    this.name = 'HapError';
+  }
+}

package/node_modules/@hap/core/src/frame.ts

@@ -1,102 +1,29 @@
 /**
- * Frame Canonicalization for Agent Profiles
+ * Bounds & Scope Canonicalization (protocol.md → *Bounds & Scope
+ * Canonicalization*).
  *
- * Agent profiles support mixed-type fields (strings and numbers).
  * Canonical form: `key=value` records joined with LF, keys in the profile's
  * keyOrder. Values are stringified with String(value) — the shortest
  * round-trippable form for numbers — then percent-encoded per protocol.md
  * (`=`, `%`, and every byte outside printable ASCII); a value carrying a raw
  * LF/CR is refused, never normalized. See `canonicalRecords` below.
  *
- * v0.3: frameSchema
- * v0.4: boundsSchema + contextSchema (separate hashes)
+ * v0.3's `frameSchema` / `canonicalFrame` / `computeFrameHash` are retired
+ * with the rest of v0.3 (CLAUDE.md "Decided by the owner": no backward
+ * compatibility). v0.7 renames `contextSchema` → `scopeSchema` and
+ * `AgentContextParams` → `AgentScopeParams` (protocol.md → *Migration from
+ * v0.6*); the functions below follow suit (`canonicalContext` →
+ * `canonicalScope`, `computeContextHash` → `computeScopeHash`,
+ * `validateContextParams` → `validateScopeParams`).
  */
 
 import { createHash } from 'crypto';
-import type { AgentFrameParams, AgentBoundsParams, AgentContextParams, AgentProfile, BoundType } from './types';
+import type { AgentBoundsParams, AgentScopeParams, AgentProfile } from './types';
 
-// ─── v0.3 Frame Functions ─────────────────────────────────────────────────────
+// ─── Bounds Validation ────────────────────────────────────────────────────────
 
 /**
- * Validates frame parameters against the profile's frame schema.
- */
-export function validateFrameParams(
-  params: AgentFrameParams,
-  profile: AgentProfile
-): { valid: boolean; errors: string[] } {
-  const errors: string[] = [];
-
-  if (!profile.frameSchema) {
-    return { valid: false, errors: ['Profile does not have a frameSchema'] };
-  }
-
-  // Check all required fields are present
-  for (const [fieldName, fieldDef] of Object.entries(profile.frameSchema.fields)) {
-    if (fieldDef.required && !(fieldName in params)) {
-      errors.push(`Missing required field: ${fieldName}`);
-    }
-  }
-
-  // Validate each provided field
-  for (const [field, value] of Object.entries(params)) {
-    const fieldDef = profile.frameSchema.fields[field];
-    if (!fieldDef) {
-      errors.push(`Unknown field "${field}" not defined in profile ${profile.id}`);
-      continue;
-    }
-
-    // Type check
-    if (fieldDef.type === 'number' && typeof value !== 'number') {
-      errors.push(`Field "${field}" must be a number, got ${typeof value}`);
-    }
-    if (fieldDef.type === 'string' && typeof value !== 'string') {
-      errors.push(`Field "${field}" must be a string, got ${typeof value}`);
-    }
-  }
-
-  return { valid: errors.length === 0, errors };
-}
-
-/**
- * Builds the canonical frame string from parameters.
- * All values are converted to strings. Keys are ordered per profile's keyOrder.
- *
- * @throws Error if any field fails validation
- */
-export function canonicalFrame(params: AgentFrameParams, profile: AgentProfile): string {
-  const validation = validateFrameParams(params, profile);
-  if (!validation.valid) {
-    throw new Error(`Invalid frame parameters: ${validation.errors.join('; ')}`);
-  }
-
-  const lines = profile.frameSchema!.keyOrder.map(
-    (key) => `${key}=${String(params[key])}`
-  );
-
-  return lines.join('\n');
-}
-
-/**
- * Computes the frame hash from a canonical frame string.
- *
- * @returns Hash in format "sha256:<64 hex chars>"
- */
-export function frameHash(canonicalFrameString: string): string {
-  const hash = createHash('sha256').update(canonicalFrameString, 'utf8').digest('hex');
-  return `sha256:${hash}`;
-}
-
-/**
- * Convenience: builds canonical frame and computes hash in one step.
- */
-export function computeFrameHash(params: AgentFrameParams, profile: AgentProfile): string {
-  return frameHash(canonicalFrame(params, profile));
-}
-
-// ─── v0.4 Bounds Functions ────────────────────────────────────────────────────
-
-/**
- * Validates bounds parameters against the profile's boundsSchema (v0.4).
+ * Validates bounds parameters against the profile's boundsSchema.
  */
 export function validateBoundsParams(
   params: AgentBoundsParams,
@@ -135,25 +62,27 @@ export function validateBoundsParams(
   return { valid: errors.length === 0, errors };
 }
 
+// ─── Scope Validation ─────────────────────────────────────────────────────────
+
 /**
- * Validates context parameters against the profile's contextSchema (v0.4).
+ * Validates scope parameters against the profile's scopeSchema.
  */
-export function validateContextParams(
-  params: AgentContextParams,
+export function validateScopeParams(
+  params: AgentScopeParams,
   profile: AgentProfile
 ): { valid: boolean; errors: string[] } {
   const errors: string[] = [];
 
-  if (!profile.contextSchema) {
-    // No contextSchema is valid — empty context
+  if (!profile.scopeSchema) {
+    // No scopeSchema is valid — empty scope
     if (Object.keys(params).length > 0) {
-      errors.push('Profile does not have a contextSchema but context params were provided');
+      errors.push('Profile does not have a scopeSchema but scope params were provided');
     }
     return { valid: errors.length === 0, errors };
   }
 
   // Check all required fields are present
-  for (const [fieldName, fieldDef] of Object.entries(profile.contextSchema.fields)) {
+  for (const [fieldName, fieldDef] of Object.entries(profile.scopeSchema.fields)) {
     if (fieldDef.required && !(fieldName in params)) {
       errors.push(`Missing required field: ${fieldName}`);
     }
@@ -161,9 +90,9 @@ export function validateContextParams(
 
   // Validate each provided field
   for (const [field, value] of Object.entries(params)) {
-    const fieldDef = profile.contextSchema.fields[field];
+    const fieldDef = profile.scopeSchema.fields[field];
     if (!fieldDef) {
-      errors.push(`Unknown field "${field}" not defined in contextSchema of profile ${profile.id}`);
+      errors.push(`Unknown field "${field}" not defined in scopeSchema of profile ${profile.id}`);
       continue;
     }
 
@@ -179,69 +108,7 @@ export function validateContextParams(
   return { valid: errors.length === 0, errors };
 }
 
-/**
- * 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.
- */
-export function validateBoundsRequiredFor(profile: AgentProfile): string[] {
-  const errors: string[] = [];
-  const boundsSchema = profile.boundsSchema;
-  if (!boundsSchema) return errors;
-
-  const actionTypes = boundsSchema.actionTypes ? [...boundsSchema.actionTypes] : undefined;
-
-  for (const [fieldName, fieldDef] of Object.entries(boundsSchema.fields)) {
-    const bt = fieldDef.boundType as (BoundType & { requiredFor?: unknown }) | undefined;
-    if (!bt) continue;
-    const requiredFor = (bt as { requiredFor?: unknown }).requiredFor;
-    if (requiredFor === undefined) 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}") — 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.`,
-          );
-        }
-      }
-    }
-    // No actionTypes registry declared: membership cannot be checked (same
-    // tolerance the AS receipt route applies to pre-registry profiles).
-  }
-
-  return errors;
-}
-
-// ─── Value Encoding (normative, v0.5+) ───────────────────────────────────────
+// ─── Value Encoding (normative, protocol.md → *Bounds & Scope Canonicalization*) ─
 
 /**
  * Thrown when a value cannot be canonicalized at all — currently only for raw
@@ -255,10 +122,10 @@ export function validateBoundsRequiredFor(profile: AgentProfile): string[] {
  *    does not faithfully represent the input."
  */
 export class CanonicalValueError extends Error {
-  readonly code: 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE';
+  readonly code: 'BOUNDS_INVALID_VALUE' | 'SCOPE_INVALID_VALUE';
   readonly field: string;
 
-  constructor(code: 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE', field: string, message: string) {
+  constructor(code: 'BOUNDS_INVALID_VALUE' | 'SCOPE_INVALID_VALUE', field: string, message: string) {
     super(message);
     this.name = 'CanonicalValueError';
     this.code = code;
@@ -275,7 +142,9 @@ export class CanonicalValueError extends Error {
  *   - every byte outside printable ASCII 0x20–0x7E
  *
  * LF and CR are deliberately NOT in this list: they are refused upstream, so
- * encoding them is unreachable (v0.7 removed the spec's contradiction here).
+ * encoding them is unreachable (v0.7 removed the spec's own contradiction here
+ * — earlier versions listed them in the percent-encode rule too, which read
+ * as permission to encode what the line above already refuses).
  *
  * This runs at canonicalization time only. Stored values keep the human's
  * original bytes.
@@ -294,7 +163,7 @@ function percentEncodeCanonicalValue(raw: string): string {
 }
 
 /**
- * The one place `key=value` records are built for bounds and context.
+ * The one place `key=value` records are built for bounds and scope.
  *
  * Rules applied here (all normative, protocol.md → *Bounds & Scope
  * Canonicalization*):
@@ -306,7 +175,7 @@ function percentEncodeCanonicalValue(raw: string): string {
  *   - a key with no value is OMITTED entirely — it emits no record
  *
  * On the omission rule: required keys are guaranteed present by the caller's
- * validation (`validateBoundsParams` / `validateContextParams` reject a missing
+ * validation (`validateBoundsParams` / `validateScopeParams` reject a missing
  * required field), so "explicit inclusion of all required keys" still holds.
  * What remains are *optional* keys the human never set. Rendering those as the
  * literal string "undefined" — the pre-fix behaviour — hashed a JavaScript
@@ -319,7 +188,7 @@ function percentEncodeCanonicalValue(raw: string): string {
 function canonicalRecords(
   params: Record<string, string | number | undefined>,
   keyOrder: string[],
-  code: 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE',
+  code: 'BOUNDS_INVALID_VALUE' | 'SCOPE_INVALID_VALUE',
 ): string {
   const lines: string[] = [];
 
@@ -361,30 +230,30 @@ export function canonicalBounds(params: AgentBoundsParams, profile: AgentProfile
 }
 
 /**
- * Builds the canonical context string from parameters.
- * Keys are ordered per profile's contextSchema.keyOrder; values are encoded per
+ * Builds the canonical scope string from parameters.
+ * Keys are ordered per profile's scopeSchema.keyOrder; values are encoded per
  * protocol.md → *Value encoding* (see `canonicalRecords`).
- * For empty context (no contextSchema or no fields), returns "".
+ * For empty scope (no scopeSchema or no fields), returns "".
  *
  * @throws Error if any field fails validation
- * @throws CanonicalValueError (code CONTEXT_INVALID_VALUE) if a value carries a raw LF/CR
+ * @throws CanonicalValueError (code SCOPE_INVALID_VALUE) if a value carries a raw LF/CR
  */
-export function canonicalContext(params: AgentContextParams, profile: AgentProfile): string {
-  // No contextSchema or no fields → empty context
-  if (!profile.contextSchema || Object.keys(profile.contextSchema.fields).length === 0) {
+export function canonicalScope(params: AgentScopeParams, profile: AgentProfile): string {
+  // No scopeSchema or no fields → empty scope
+  if (!profile.scopeSchema || Object.keys(profile.scopeSchema.fields).length === 0) {
     return '';
   }
 
-  const validation = validateContextParams(params, profile);
+  const validation = validateScopeParams(params, profile);
   if (!validation.valid) {
-    throw new Error(`Invalid context parameters: ${validation.errors.join('; ')}`);
+    throw new Error(`Invalid scope parameters: ${validation.errors.join('; ')}`);
   }
 
-  return canonicalRecords(params, profile.contextSchema.keyOrder, 'CONTEXT_INVALID_VALUE');
+  return canonicalRecords(params, profile.scopeSchema.keyOrder, 'SCOPE_INVALID_VALUE');
 }
 
 /**
- * Computes the bounds hash from bounds parameters (v0.4).
+ * Computes the bounds hash from bounds parameters.
  *
  * @returns Hash in format "sha256:<64 hex chars>"
  */
@@ -395,14 +264,14 @@ export function computeBoundsHash(params: AgentBoundsParams, profile: AgentProfi
 }
 
 /**
- * Computes the context hash from context parameters (v0.4).
- * For empty context {}, returns the sha256 of "":
+ * Computes the scope hash from scope parameters.
+ * For empty scope {}, returns the sha256 of "":
  *   "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  *
  * @returns Hash in format "sha256:<64 hex chars>"
  */
-export function computeContextHash(params: AgentContextParams, profile: AgentProfile): string {
-  const canonical = canonicalContext(params, profile);
+export function computeScopeHash(params: AgentScopeParams, profile: AgentProfile): string {
+  const canonical = canonicalScope(params, profile);
   const hash = createHash('sha256').update(canonical, 'utf8').digest('hex');
   return `sha256:${hash}`;
 }