@suveren/gateway 0.7.4 → 0.8.0

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

@@ -14,7 +14,7 @@ interface ResolvedDomain {
 }
 interface AttestationPayload {
     attestation_id: string;
-    version: '0.3' | '0.4' | '0.5';
+    version: '0.3' | '0.4' | '0.5' | '0.6';
     profile_id: string;
     /** v0.3 (deprecated) — hash of the authorization frame */
     frame_hash?: string;
@@ -62,11 +62,51 @@ interface AttestationPayload {
      *
      * Cryptographically bound in the signed payload so a compromised SP cannot
      * silently flip 'review' → 'automatic'. Absent on v0.3 attestations.
+     * `review_above_cap` (v0.5): automatic below the signed caps, proposal above.
      */
-    commitment_mode?: 'automatic' | 'review';
+    commitment_mode?: 'automatic' | 'review' | 'review_above_cap';
+    /**
+     * v0.6 (Owner Mandate Signatures) — the Decision Owner's own signature(s)
+     * over the mandate projection ({@link MandateProjection}), one entry per
+     * co-signing owner. Carried INSIDE the AS-signed payload, so the AS attests
+     * to having received it and cannot strip it without invalidating its own
+     * signature. Optional and additive: an attestation without it behaves as
+     * before (the v0.5 posture — the AS asserts, nobody co-signs).
+     */
+    owner_mandates?: OwnerMandate[];
     issued_at: number;
     expires_at: number;
 }
+/** Mandate-assurance axis — what custody signed the mandate. Independent of
+ * identity assurance ({@link Subject.method}). */
+type MandateBinding = 'raw' | 'webauthn' | 'eudi';
+/** Which surface showed the owner what they signed. A DECLARATION, not a proof
+ * — no verifier can check it; see protocol.md → Owner Mandate Signatures. */
+type SigningSurface = 'gatekeeper_local' | 'as_web' | 'wallet_display';
+/**
+ * v0.6 — one owner's signature over the mandate projection.
+ *
+ * There is deliberately NO `public_key` field, and it MUST NOT be added: the
+ * verification key is carried in the DID itself (key-bearing `did:key`), so a
+ * non-key-bearing DID fails STRUCTURALLY instead of validating against a key
+ * the AS could have substituted. `alg` is kept only as curve-confusion
+ * hygiene; if it disagrees with the DID's key type, the DID is authoritative.
+ */
+interface OwnerMandate {
+    /** The signing owner's key-bearing DID. MUST be a member of `resolved_owners`. */
+    did: string;
+    /** Signature algorithm hint. The DID's multicodec wins on any disagreement. */
+    alg: 'EdDSA' | 'ES256';
+    /** base64url (no padding) signature over the JCS bytes of the mandate projection. */
+    signature: string;
+    /** When the owner signed (unix seconds). */
+    signed_at: number;
+    /** Defence-in-depth against duplicate issuance by an HONEST AS only —
+     * AS-side nonce enforcement is no defence against the AS itself. */
+    nonce: string;
+    binding: MandateBinding;
+    signing_surface?: SigningSurface;
+}
 /**
  * v0.6 Identity Assurance — a signed overlay binding a Decision Owner's verified
  * real-world identity to the attestation, gated by HOW the identity was verified.
@@ -94,8 +134,11 @@ interface Subject {
     /** When the underlying verification was performed (unix seconds). */
     verified_at?: number;
     /**
-     * eudi only (Phase 2) — the owner's per-event wallet signature, making the
-     * identity claim non-repudiable independent of the AS. Null/absent otherwise.
+     * @deprecated v0.6 — replaced by {@link AttestationPayload.owner_mandates}.
+     * This field signed the wrong object (the identity claim, not what was
+     * committed to) and was welded to one method. Implementations MUST NOT emit
+     * it; verifiers MAY ignore it on artifacts that carry it. Kept readable for
+     * audit of pre-0.6 artifacts only.
      */
     owner_signature?: string | null;
 }
@@ -334,6 +377,15 @@ interface ProfileContextField {
     description?: string;
     displayName?: string;
     format?: 'email' | 'domain' | 'url' | 'currency';
+    /**
+     * v0.6 — what this field NAMES on the read path. `counterparty` = the other
+     * party to a communication (matched against an item's participants);
+     * `resource` = the container an item belongs to (a direct attribute match —
+     * and a resource scope enforced on writes MUST also bind reads). Absent →
+     * implementations MAY infer `counterparty` from `format: email|domain`
+     * (transitional; the explicit declaration is normative).
+     */
+    scopeKind?: 'counterparty' | 'resource';
     constraint?: FieldConstraint;
     enum?: string[];
 }
@@ -604,7 +656,7 @@ interface GatekeeperRequest {
  * Structured error from Gatekeeper verification.
  */
 interface GatekeeperError {
-    code: 'BOUND_EXCEEDED' | 'CUMULATIVE_LIMIT_EXCEEDED' | 'INVALID_SIGNATURE' | 'TTL_EXPIRED' | 'FRAME_MISMATCH' | 'BOUNDS_MISMATCH' | 'CONTEXT_MISMATCH' | 'DOMAIN_NOT_COVERED' | 'INVALID_PROFILE' | 'MALFORMED_ATTESTATION';
+    code: 'BOUND_EXCEEDED' | 'CUMULATIVE_LIMIT_EXCEEDED' | 'INVALID_SIGNATURE' | 'TTL_EXPIRED' | 'FRAME_MISMATCH' | 'BOUNDS_MISMATCH' | 'CONTEXT_MISMATCH' | 'DOMAIN_NOT_COVERED' | 'INVALID_PROFILE' | 'MALFORMED_ATTESTATION' | 'INVALID_ACTION_TYPE' | 'ATTESTATION_REVOKED' | 'APPROVAL_REQUIRED' | 'IDEMPOTENCY_MISMATCH' | 'MANDATE_SIGNATURE_REQUIRED' | 'MANDATE_SIGNATURE_INVALID' | 'APPROVAL_SIGNATURE_REQUIRED' | 'APPROVAL_SIGNATURE_INVALID' | 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE';
     field?: string;
     message: string;
     bound?: string | number;
@@ -824,10 +876,22 @@ interface SubjectValidation {
  * Enforce the Identity-Assurance invariants on a single subject:
  *  - `self_declared` ⇒ `low` / `self`, no disclosed name.
  *  - `as_vouched`    ⇒ `high` / `as`,  `verifier` required.
- *  - `eudi`          ⇒ `high` / `external`, `verifier` + `owner_signature` required.
+ *  - `eudi`          ⇒ `high` / `external`, `verifier` required — and, when the
+ *    carrying attestation's `owner_mandates` are supplied, a corresponding
+ *    entry with `binding:"eudi"` for this subject's DID.
  *  - `disclose.name` only at `assurance:"high"`.
- */
-declare function validateSubject(subject: Subject): SubjectValidation;
+ *
+ * v0.6: `Subject.owner_signature` is deprecated and IGNORED here — it signed
+ * the identity claim, not the mandate (see the field's deprecation note). The
+ * signature-bearing object is the attestation's `owner_mandates` entry, which
+ * is payload-level context this per-subject check cannot see on its own; pass
+ * `opts.ownerMandates` to enforce the eudi ⇒ mandate-entry rule, omit it to
+ * validate subject shape alone (pre-0.6 callers keep their behaviour minus
+ * the retired owner_signature requirement).
+ */
+declare function validateSubject(subject: Subject, opts?: {
+    ownerMandates?: OwnerMandate[];
+}): SubjectValidation;
 /**
  * The footer line for a subject — the ONE place this wording lives.
  * The name appears only at `high` with a disclosed name; otherwise no name.
@@ -857,8 +921,11 @@ declare function deriveIdentityLine(subject: Subject | undefined | null, { opera
  * Frame Canonicalization for Agent Profiles
  *
  * Agent profiles support mixed-type fields (strings and numbers).
- * Canonical form: all values are converted to strings via String(value).
- * Keys are ordered according to the profile's keyOrder.
+ * 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)
@@ -902,19 +969,39 @@ declare function validateContextParams(params: AgentContextParams, profile: Agen
     valid: boolean;
     errors: 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
+ * straight onto the wire without string-matching a message.
+ *
+ * protocol.md → *Bounds & Scope Canonicalization* → Value encoding:
+ *   "Values MUST NOT contain raw newline (\n) or carriage-return (\r)
+ *    characters. Implementations MUST reject input containing them; silent
+ *    stripping or normalization is a violation because it produces a hash that
+ *    does not faithfully represent the input."
+ */
+declare class CanonicalValueError extends Error {
+    readonly code: 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE';
+    readonly field: string;
+    constructor(code: 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE', field: string, message: string);
+}
 /**
  * Builds the canonical bounds string from parameters.
- * All values are converted to strings. Keys are ordered per profile's boundsSchema.keyOrder.
+ * Keys are ordered per profile's boundsSchema.keyOrder; values are encoded per
+ * protocol.md → *Value encoding* (see `canonicalRecords`).
  *
  * @throws Error if any field fails validation
+ * @throws CanonicalValueError (code BOUNDS_INVALID_VALUE) if a value carries a raw LF/CR
  */
 declare function canonicalBounds(params: AgentBoundsParams, profile: AgentProfile): string;
 /**
  * Builds the canonical context string from parameters.
- * All values are converted to strings. Keys are ordered per profile's contextSchema.keyOrder.
+ * Keys are ordered per profile's contextSchema.keyOrder; values are encoded per
+ * protocol.md → *Value encoding* (see `canonicalRecords`).
  * For empty context (no contextSchema 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
  */
 declare function canonicalContext(params: AgentContextParams, profile: AgentProfile): string;
 /**
@@ -1050,4 +1137,189 @@ declare function listProfiles(): string[];
 declare function getAllProfiles(): AgentProfile[];
 declare function clearProfiles(): void;
 
-export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type Attestation, type AttestationHeader, type AttestationPayload, type BoundType, 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 ProfileBoundsField, type ProfileContextField, type ProfileFrameField, type ProfileToolGating, type ProfileToolGatingEntry, type ResolvedDomain, type Subject, type SubjectValidation, attestationId, bindingAppliesTo, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFieldsContentHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, deriveIdentityLine, encodeAttestationBlob, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isFieldBinding, isV4Attestation, listProfiles, registerProfile, selectBoundFields, validateBoundsParams, validateContextParams, validateFrameParams, validateSubject, verify, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash };
+/**
+ * did:key — encode/decode for KEY-BEARING DIDs (HAP v0.6).
+ *
+ * A real `did:key` is self-certifying: the public key IS the identifier, so
+ * substituting the key produces a DIFFERENT DID and no key directory is ever
+ * consulted. That property is what the Owner Mandate design stands on
+ * (protocol.md → "Identity DIDs vs signing DIDs"): a signing DID MUST be
+ * key-bearing, and verification uses the key carried in the identifier —
+ * deliberately, there is no `public_key` field anywhere on the wire.
+ *
+ * Format (W3C did:key method, Ed25519):
+ *   did:key:z<base58btc( 0xed 0x01 ‖ 32-byte-public-key )>
+ * `z` is the multibase prefix for base58btc; `0xed 0x01` is the multicodec
+ * varint for ed25519-pub. The result always starts `did:key:z6Mk`.
+ *
+ * Scope: Ed25519 only — the one signing curve this protocol version uses.
+ * Anything else (including the reference implementation's legacy decorative
+ * `did:key:<uuid-fragment>` identifiers) decodes as NOT key-bearing.
+ */
+/** Encode a 32-byte Ed25519 public key as a key-bearing `did:key:z6Mk…`. */
+declare function encodeDidKey(publicKey: Uint8Array): string;
+/**
+ * Decode a key-bearing `did:key` to its Ed25519 public key bytes.
+ *
+ * @throws Error prefixed `NOT_KEY_BEARING:` for anything that is not a valid
+ * base58btc-multibase Ed25519 did:key — including the legacy decorative
+ * `did:key:<uuid-fragment>` identifiers, other multibase prefixes, and other
+ * key types. The error name is the point: under the mandate design, a
+ * non-key-bearing signing DID must fail STRUCTURALLY, never fall back.
+ */
+declare function decodeDidKey(did: string): Uint8Array;
+/** True iff the DID decodes as a key-bearing Ed25519 did:key. Never throws. */
+declare function isKeyBearingDid(did: string): boolean;
+
+/**
+ * Owner Mandate Signatures (HAP v0.6) — the `HAP-mandate` projection, the
+ * `HAP-approval` object, and their verification.
+ *
+ * The human signs BEFORE the AS does, so they cannot sign the finished
+ * attestation (`attestation_id`/`issued_at` do not exist yet). They sign a
+ * mandate PROJECTION: a canonical object every field of which is known at
+ * approval time and reconstructible from the finished attestation — so a
+ * verifier rebuilds it from the attestation it already holds and checks the
+ * signature with the key carried in the owner's DID. No side channel, no
+ * second fetch, no key directory. See protocol.md → "Owner Mandate Signatures".
+ *
+ * Verification here requires NO trust in the AS. What it cannot do is tell the
+ * verifier WHOSE key signed — confirming the DID belongs to the expected
+ * person is the out-of-band step (protocol.md → "Identity DIDs vs signing
+ * DIDs"), and it is the honest cost of cold verification.
+ */
+
+/** The object the owner signs — a canonical projection of the mandate. */
+interface MandateProjection {
+    typ: 'HAP-mandate';
+    /** Projection/canonicalization version. A verifier MUST pin it. */
+    version: '0.6';
+    profile_id: string;
+    /** The signing owner's own DID. MUST be a member of `resolved_owners`. */
+    owner_did: string;
+    bounds_hash: string;
+    context_hash: string;
+    execution_context_hash: string;
+    gate_content_hashes: Record<string, string>;
+    /** Included iff the attestation carries one — binds ciphertext AND the
+     * frozen approver set, the swap this mechanism exists to stop. */
+    intent_disclosure_hash?: string;
+    commitment_mode: string;
+    /** The replay defence: the human signs how long the authority lives. */
+    expires_at: number;
+    nonce: string;
+}
+/** Per-action approval, signed by the owner in `review` mode. Signing a
+ * `reject` matters as much as a `commit`: a rejection the AS can discard is a
+ * rejection that never happened. */
+interface ApprovalObject {
+    typ: 'HAP-approval';
+    version: '0.6';
+    proposal_id: string;
+    attestation_id: string;
+    decision: 'commit' | 'reject';
+    /** What was approved: the receipt's contentHash where the profile binds
+     * content; otherwise sha256 over the JCS of the proposal's argument set. */
+    content_hash: string;
+    decided_at: number;
+    nonce: string;
+}
+declare class MandateError extends Error {
+    code: 'MANDATE_SIGNATURE_INVALID' | 'APPROVAL_SIGNATURE_INVALID' | 'NOT_KEY_BEARING' | 'OWNER_NOT_RESOLVED' | 'MALFORMED_ATTESTATION';
+    constructor(code: 'MANDATE_SIGNATURE_INVALID' | 'APPROVAL_SIGNATURE_INVALID' | 'NOT_KEY_BEARING' | 'OWNER_NOT_RESOLVED' | 'MALFORMED_ATTESTATION', message: string);
+}
+/**
+ * Rebuild the projection a given `owner_mandates` entry signed, from the
+ * attestation's own signed fields. Field absence is defined, not incidental:
+ * `intent_disclosure_hash` is included iff the attestation carries one.
+ */
+declare function buildMandateProjection(payload: AttestationPayload, entry: Pick<OwnerMandate, 'did' | 'nonce'>): MandateProjection;
+/** The exact bytes an owner signs: RFC 8785 (JCS) canonical UTF-8. */
+declare function mandateSigningBytes(projection: MandateProjection): Uint8Array;
+/** The exact bytes an owner signs for a per-action approval. */
+declare function approvalSigningBytes(approval: ApprovalObject): Uint8Array;
+/**
+ * Sign a mandate projection with a raw Ed25519 private key — the `raw`
+ * binding: tests and CI only, no custody claim. WebAuthn (`webauthn`) and
+ * wallet (`eudi`) bindings sign the same bytes through their own custody;
+ * they are implemented by the platforms that hold those keys, not here.
+ */
+declare function signMandateProjection(projection: MandateProjection, privateKey: Uint8Array): Promise<string>;
+/** Sign an approval object with a raw Ed25519 private key (`raw` binding). */
+declare function signApproval(approval: ApprovalObject, privateKey: Uint8Array): Promise<string>;
+/**
+ * Verify ONE `owner_mandates` entry against the attestation that carries it.
+ *
+ * Steps (protocol.md → "Verification procedure", steps 4 of 6): membership in
+ * `resolved_owners`, key-bearing DID, projection reconstruction, Ed25519 over
+ * JCS bytes. The DID is authoritative over `alg` — a disagreement is
+ * MANDATE_SIGNATURE_INVALID, never a fallback to the claimed algorithm.
+ *
+ * What this deliberately does NOT verify: that the DID belongs to the person
+ * the verifier expects (out-of-band, step 5) and the AS's own signature over
+ * the attestation (verifyAttestationSignature, step 1).
+ */
+declare function verifyOwnerMandate(attestation: Attestation, entry: OwnerMandate): Promise<void>;
+/** Verify every `owner_mandates` entry an attestation carries. Resolves to the
+ * verified entries; an attestation with none resolves to `[]` (the v0.5
+ * posture — nothing to check, and nothing claimed). */
+declare function verifyOwnerMandates(attestation: Attestation): Promise<OwnerMandate[]>;
+/** Verify an approval signature against a signer's key-bearing DID. */
+declare function verifyApproval(approval: ApprovalObject, signature: string, signerDid: string): Promise<void>;
+
+/**
+ * Execution receipts (HAP v0.5/v0.6) — the wire type and holder-side
+ * verification. Until v0.6 this library had no receipt surface at all; every
+ * verifier hand-assembled the strip→canonicalize→verify dance. This module is
+ * that dance, once.
+ *
+ * Receipt payloads are camelCase on the wire (unlike the snake_case
+ * attestation payload) — a shipped inconsistency v0.6 chose to document
+ * rather than break (changelog.md → "Renames and terminology").
+ */
+
+/** Signed execution receipt — protocol.md → "Receipt Payload Schema". */
+interface ReceiptPayload {
+    id: string;
+    groupId?: string | null;
+    userId?: string;
+    boundsHash: string;
+    profileId: string;
+    /** Downstream tool name. Audit metadata only — never a dispatch key. */
+    action: string;
+    /** Semantic category — drives cumulative bucketing and bounds dispatch. */
+    actionType: string;
+    executionContext: Record<string, unknown>;
+    cumulativeState?: Record<string, unknown>;
+    limits?: Record<string, unknown>;
+    timestamp: number;
+    /** v0.6 — hash of the bound content, computed by the Gatekeeper, copied
+     * verbatim by the AS. The AS never sees the content. */
+    contentHash?: string;
+    /** v0.6 — the binding declaration echoed into the signed receipt, so a
+     * verifier knows exactly what `contentHash` covers. */
+    contentBinding?: Pick<ContentBinding, 'version' | 'kind' | 'fields' | 'required_fields' | 'appliesTo'>;
+    /** v0.6 — disclosed subset of the attestation's identity overlay. */
+    subjects?: Subject[];
+    /** v0.6 — review path: the proposal this receipt executed. */
+    proposalId?: string;
+    /** v0.6 — review path: the owner's HAP-approval signature (or its sha256)
+     * for the executed proposal. */
+    approvalSignature?: string;
+    /** Ed25519 over the JCS-canonical payload (this field excluded), base64url. */
+    signature: string;
+}
+/**
+ * Verify a receipt's AS signature: strip `signature`, JCS-canonicalize the
+ * rest, Ed25519-verify against the AS public key (hex). This is holder-side
+ * verification — it needs the COMPLETE receipt; a redacted public view cannot
+ * be re-verified this way (protocol.md → "Receipt Verification").
+ *
+ * Content is checked separately: where `contentHash` is present, recompute it
+ * from the held artifact via the content-binding module and compare.
+ *
+ * @throws Error prefixed `INVALID_SIGNATURE:` when verification fails.
+ */
+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, 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 };