@humanagencyp/hap-core 0.5.2 → 0.6.1

package/dist/index.d.mts

@@ -46,6 +46,14 @@ interface AttestationPayload {
      * without invalidating the attestation signature (companion invariant C2).
      */
     intent_disclosure_hash?: string;
+    /**
+     * v0.6 (Identity Assurance) — optional signed overlay carrying the verified
+     * real-world identity of the Decision Owner(s), one entry per owner. Present
+     * only when identity is disclosed; an attestation with no `subjects` renders
+     * as `low` (pseudonymous, no name). See {@link Subject} and
+     * {@link deriveIdentityLine}.
+     */
+    subjects?: Subject[];
     /**
      * v0.4 — commitment mode chosen by the decision owner at attestation time.
      * - 'automatic': agent may invoke bounded tools without per-action review.
@@ -59,6 +67,38 @@ interface AttestationPayload {
     issued_at: number;
     expires_at: number;
 }
+/**
+ * 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.
+ *
+ * Two display levels (`assurance`): `low` discloses no name; `high` MAY disclose a
+ * name. At `high`, two trust roots: `as` (the AS operator vouches — valid only
+ * within its own domain) and `external` (an external eID such as EUDI — carries the
+ * owner's own signature, AS-independent). See review.md → "Identity Assurance".
+ */
+interface Subject {
+    /** The Decision Owner DID this subject describes (matches an entry in resolved_owners). */
+    did: string;
+    /** `low` → no name shown; `high` → the name MAY be shown. */
+    assurance: 'low' | 'high';
+    /** How identity was established. */
+    method: 'self_declared' | 'as_vouched' | 'eudi';
+    /** Who vouches: `self` (owner's claim), `as` (operator), `external` (eID scheme). */
+    trust_root: 'self' | 'as' | 'external';
+    /** Verifier id — the AS operator (as_vouched) or the eID scheme (eudi). Required at `high`. */
+    verifier?: string;
+    /** Disclosed attributes. `name` present ONLY at `assurance:"high"` and when disclosure is on. */
+    disclose?: {
+        name: string;
+    };
+    /** 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.
+     */
+    owner_signature?: string | null;
+}
 interface Attestation {
     header: AttestationHeader;
     payload: AttestationPayload;
@@ -585,6 +625,48 @@ declare function intentDisclosureCanonicalBytes(intentCiphertext: string, approv
  */
 declare function computeIntentDisclosureHash(intentCiphertext: string, approversFrozen: string[]): string;
 
+/**
+ * Identity Assurance (HAP v0.6) — validation + footer derivation for the signed
+ * {@link Subject} overlay. See review.md → "Identity Assurance".
+ *
+ * Two pure helpers, the single source of truth for both the gateway footer and
+ * the AS verify page:
+ *  - {@link validateSubject} — enforces the level/method/trust-root invariants.
+ *  - {@link deriveIdentityLine} — the human-readable footer line for a subject.
+ */
+
+interface SubjectValidation {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * 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.
+ *  - `disclose.name` only at `assurance:"high"`.
+ */
+declare function validateSubject(subject: Subject): 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.
+ *
+ *  - low / no disclosure → "Sent by an AI agent via «operator»"
+ *  - high / as_vouched   → "Sent by an AI agent of «name», verified by «operator»"
+ *  - high / eudi         → "Sent by an AI agent of «name», identity verified (EUDI)"
+ *
+ * Punctuation is ASCII (comma, not em-dash) so the line survives header and
+ * plain-text encoding intact across email, calendar, and publishing channels.
+ * The leading verb ("Sent") is the default; presentation layers may swap it
+ * (e.g. the gateway uses "Published" for the publish profile).
+ *
+ * `operatorName` is the rendered AS operator (e.g. "Suveren") — never hardcode it
+ * upstream; a different operator self-vouches under its own name.
+ */
+declare function deriveIdentityLine(subject: Subject | undefined | null, { operatorName }: {
+    operatorName: string;
+}): string;
+
 /**
  * Frame Canonicalization for Agent Profiles
  *
@@ -782,4 +864,4 @@ 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, 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, attestationId, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, encodeAttestationBlob, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isV4Attestation, listProfiles, registerProfile, validateBoundsParams, validateContextParams, validateFrameParams, verify, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash };
+export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type Attestation, type AttestationHeader, type AttestationPayload, type BoundType, type ContentBinding, 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, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, deriveIdentityLine, encodeAttestationBlob, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isV4Attestation, listProfiles, registerProfile, validateBoundsParams, validateContextParams, validateFrameParams, validateSubject, verify, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash };

package/dist/index.d.ts

@@ -46,6 +46,14 @@ interface AttestationPayload {
      * without invalidating the attestation signature (companion invariant C2).
      */
     intent_disclosure_hash?: string;
+    /**
+     * v0.6 (Identity Assurance) — optional signed overlay carrying the verified
+     * real-world identity of the Decision Owner(s), one entry per owner. Present
+     * only when identity is disclosed; an attestation with no `subjects` renders
+     * as `low` (pseudonymous, no name). See {@link Subject} and
+     * {@link deriveIdentityLine}.
+     */
+    subjects?: Subject[];
     /**
      * v0.4 — commitment mode chosen by the decision owner at attestation time.
      * - 'automatic': agent may invoke bounded tools without per-action review.
@@ -59,6 +67,38 @@ interface AttestationPayload {
     issued_at: number;
     expires_at: number;
 }
+/**
+ * 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.
+ *
+ * Two display levels (`assurance`): `low` discloses no name; `high` MAY disclose a
+ * name. At `high`, two trust roots: `as` (the AS operator vouches — valid only
+ * within its own domain) and `external` (an external eID such as EUDI — carries the
+ * owner's own signature, AS-independent). See review.md → "Identity Assurance".
+ */
+interface Subject {
+    /** The Decision Owner DID this subject describes (matches an entry in resolved_owners). */
+    did: string;
+    /** `low` → no name shown; `high` → the name MAY be shown. */
+    assurance: 'low' | 'high';
+    /** How identity was established. */
+    method: 'self_declared' | 'as_vouched' | 'eudi';
+    /** Who vouches: `self` (owner's claim), `as` (operator), `external` (eID scheme). */
+    trust_root: 'self' | 'as' | 'external';
+    /** Verifier id — the AS operator (as_vouched) or the eID scheme (eudi). Required at `high`. */
+    verifier?: string;
+    /** Disclosed attributes. `name` present ONLY at `assurance:"high"` and when disclosure is on. */
+    disclose?: {
+        name: string;
+    };
+    /** 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.
+     */
+    owner_signature?: string | null;
+}
 interface Attestation {
     header: AttestationHeader;
     payload: AttestationPayload;
@@ -585,6 +625,48 @@ declare function intentDisclosureCanonicalBytes(intentCiphertext: string, approv
  */
 declare function computeIntentDisclosureHash(intentCiphertext: string, approversFrozen: string[]): string;
 
+/**
+ * Identity Assurance (HAP v0.6) — validation + footer derivation for the signed
+ * {@link Subject} overlay. See review.md → "Identity Assurance".
+ *
+ * Two pure helpers, the single source of truth for both the gateway footer and
+ * the AS verify page:
+ *  - {@link validateSubject} — enforces the level/method/trust-root invariants.
+ *  - {@link deriveIdentityLine} — the human-readable footer line for a subject.
+ */
+
+interface SubjectValidation {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * 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.
+ *  - `disclose.name` only at `assurance:"high"`.
+ */
+declare function validateSubject(subject: Subject): 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.
+ *
+ *  - low / no disclosure → "Sent by an AI agent via «operator»"
+ *  - high / as_vouched   → "Sent by an AI agent of «name», verified by «operator»"
+ *  - high / eudi         → "Sent by an AI agent of «name», identity verified (EUDI)"
+ *
+ * Punctuation is ASCII (comma, not em-dash) so the line survives header and
+ * plain-text encoding intact across email, calendar, and publishing channels.
+ * The leading verb ("Sent") is the default; presentation layers may swap it
+ * (e.g. the gateway uses "Published" for the publish profile).
+ *
+ * `operatorName` is the rendered AS operator (e.g. "Suveren") — never hardcode it
+ * upstream; a different operator self-vouches under its own name.
+ */
+declare function deriveIdentityLine(subject: Subject | undefined | null, { operatorName }: {
+    operatorName: string;
+}): string;
+
 /**
  * Frame Canonicalization for Agent Profiles
  *
@@ -782,4 +864,4 @@ 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, 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, attestationId, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, encodeAttestationBlob, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isV4Attestation, listProfiles, registerProfile, validateBoundsParams, validateContextParams, validateFrameParams, verify, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash };
+export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type Attestation, type AttestationHeader, type AttestationPayload, type BoundType, type ContentBinding, 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, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, deriveIdentityLine, encodeAttestationBlob, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isV4Attestation, listProfiles, registerProfile, validateBoundsParams, validateContextParams, validateFrameParams, validateSubject, verify, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash };

package/dist/index.js

@@ -46,6 +46,7 @@ __export(index_exports, {
   computeIntentHash: () => computeIntentHash,
   contentCanonicalBytes: () => contentCanonicalBytes,
   decodeAttestationBlob: () => decodeAttestationBlob,
+  deriveIdentityLine: () => deriveIdentityLine,
   encodeAttestationBlob: () => encodeAttestationBlob,
   frameHash: () => frameHash,
   getAllProfiles: () => getAllProfiles,
@@ -57,6 +58,7 @@ __export(index_exports, {
   validateBoundsParams: () => validateBoundsParams,
   validateContextParams: () => validateContextParams,
   validateFrameParams: () => validateFrameParams,
+  validateSubject: () => validateSubject,
   verify: () => verify,
   verifyAttestation: () => verifyAttestation,
   verifyAttestationSignature: () => verifyAttestationSignature,
@@ -136,6 +138,43 @@ function computeIntentDisclosureHash(intentCiphertext, approversFrozen) {
   return `sha256:${sha256Hex2(intentDisclosureCanonicalBytes(intentCiphertext, approversFrozen))}`;
 }
 
+// src/identity.ts
+function validateSubject(subject) {
+  const errors = [];
+  const { did, assurance, method, trust_root, verifier, disclose, owner_signature } = subject;
+  if (!did) errors.push("subject.did is required");
+  if (assurance === "low") {
+    if (method !== "self_declared") errors.push(`low assurance requires method "self_declared", got "${method}"`);
+    if (trust_root !== "self") errors.push(`low assurance requires trust_root "self", got "${trust_root}"`);
+    if (disclose) errors.push("low assurance MUST NOT disclose a name");
+  } else if (assurance === "high") {
+    if (method === "as_vouched") {
+      if (trust_root !== "as") errors.push('as_vouched requires trust_root "as"');
+      if (!verifier) errors.push("as_vouched requires a verifier");
+    } else if (method === "eudi") {
+      if (trust_root !== "external") errors.push('eudi requires trust_root "external"');
+      if (!verifier) errors.push("eudi requires a verifier");
+      if (!owner_signature) errors.push("eudi requires an owner_signature");
+    } else {
+      errors.push(`high assurance requires method "as_vouched" or "eudi", got "${method}"`);
+    }
+    if (disclose && typeof disclose.name !== "string") errors.push("disclose.name must be a string");
+  } else {
+    errors.push(`assurance must be "low" or "high", got "${assurance}"`);
+  }
+  return { valid: errors.length === 0, errors };
+}
+function deriveIdentityLine(subject, { operatorName }) {
+  const name = subject?.assurance === "high" ? subject.disclose?.name : void 0;
+  if (!name) {
+    return `Sent by an AI agent via ${operatorName}`;
+  }
+  if (subject.method === "eudi") {
+    return `Sent by an AI agent of ${name}, identity verified (EUDI)`;
+  }
+  return `Sent by an AI agent of ${name}, verified by ${operatorName}`;
+}
+
 // src/frame.ts
 var import_crypto3 = require("crypto");
 function validateFrameParams(params, profile) {
@@ -807,6 +846,7 @@ function resolveCumulativeFields(request, profile, executionLog, now) {
   computeIntentHash,
   contentCanonicalBytes,
   decodeAttestationBlob,
+  deriveIdentityLine,
   encodeAttestationBlob,
   frameHash,
   getAllProfiles,
@@ -818,6 +858,7 @@ function resolveCumulativeFields(request, profile, executionLog, now) {
   validateBoundsParams,
   validateContextParams,
   validateFrameParams,
+  validateSubject,
   verify,
   verifyAttestation,
   verifyAttestationSignature,

package/dist/index.mjs

@@ -67,6 +67,43 @@ function computeIntentDisclosureHash(intentCiphertext, approversFrozen) {
   return `sha256:${sha256Hex2(intentDisclosureCanonicalBytes(intentCiphertext, approversFrozen))}`;
 }
 
+// src/identity.ts
+function validateSubject(subject) {
+  const errors = [];
+  const { did, assurance, method, trust_root, verifier, disclose, owner_signature } = subject;
+  if (!did) errors.push("subject.did is required");
+  if (assurance === "low") {
+    if (method !== "self_declared") errors.push(`low assurance requires method "self_declared", got "${method}"`);
+    if (trust_root !== "self") errors.push(`low assurance requires trust_root "self", got "${trust_root}"`);
+    if (disclose) errors.push("low assurance MUST NOT disclose a name");
+  } else if (assurance === "high") {
+    if (method === "as_vouched") {
+      if (trust_root !== "as") errors.push('as_vouched requires trust_root "as"');
+      if (!verifier) errors.push("as_vouched requires a verifier");
+    } else if (method === "eudi") {
+      if (trust_root !== "external") errors.push('eudi requires trust_root "external"');
+      if (!verifier) errors.push("eudi requires a verifier");
+      if (!owner_signature) errors.push("eudi requires an owner_signature");
+    } else {
+      errors.push(`high assurance requires method "as_vouched" or "eudi", got "${method}"`);
+    }
+    if (disclose && typeof disclose.name !== "string") errors.push("disclose.name must be a string");
+  } else {
+    errors.push(`assurance must be "low" or "high", got "${assurance}"`);
+  }
+  return { valid: errors.length === 0, errors };
+}
+function deriveIdentityLine(subject, { operatorName }) {
+  const name = subject?.assurance === "high" ? subject.disclose?.name : void 0;
+  if (!name) {
+    return `Sent by an AI agent via ${operatorName}`;
+  }
+  if (subject.method === "eudi") {
+    return `Sent by an AI agent of ${name}, identity verified (EUDI)`;
+  }
+  return `Sent by an AI agent of ${name}, verified by ${operatorName}`;
+}
+
 // src/frame.ts
 import { createHash as createHash3 } from "crypto";
 function validateFrameParams(params, profile) {
@@ -737,6 +774,7 @@ export {
   computeIntentHash,
   contentCanonicalBytes,
   decodeAttestationBlob,
+  deriveIdentityLine,
   encodeAttestationBlob,
   frameHash,
   getAllProfiles,
@@ -748,6 +786,7 @@ export {
   validateBoundsParams,
   validateContextParams,
   validateFrameParams,
+  validateSubject,
   verify,
   verifyAttestation,
   verifyAttestationSignature,

package/package.json

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

package/src/identity.ts

@@ -0,0 +1,82 @@
+/**
+ * Identity Assurance (HAP v0.6) — validation + footer derivation for the signed
+ * {@link Subject} overlay. See review.md → "Identity Assurance".
+ *
+ * Two pure helpers, the single source of truth for both the gateway footer and
+ * the AS verify page:
+ *  - {@link validateSubject} — enforces the level/method/trust-root invariants.
+ *  - {@link deriveIdentityLine} — the human-readable footer line for a subject.
+ */
+
+import type { Subject } from './types';
+
+export interface SubjectValidation {
+  valid: boolean;
+  errors: string[];
+}
+
+/**
+ * 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.
+ *  - `disclose.name` only at `assurance:"high"`.
+ */
+export function validateSubject(subject: Subject): SubjectValidation {
+  const errors: string[] = [];
+  const { did, assurance, method, trust_root, verifier, disclose, owner_signature } = subject;
+
+  if (!did) errors.push('subject.did is required');
+
+  if (assurance === 'low') {
+    if (method !== 'self_declared') errors.push(`low assurance requires method "self_declared", got "${method}"`);
+    if (trust_root !== 'self') errors.push(`low assurance requires trust_root "self", got "${trust_root}"`);
+    if (disclose) errors.push('low assurance MUST NOT disclose a name');
+  } else if (assurance === 'high') {
+    if (method === 'as_vouched') {
+      if (trust_root !== 'as') errors.push('as_vouched requires trust_root "as"');
+      if (!verifier) errors.push('as_vouched requires a verifier');
+    } else if (method === 'eudi') {
+      if (trust_root !== 'external') errors.push('eudi requires trust_root "external"');
+      if (!verifier) errors.push('eudi requires a verifier');
+      if (!owner_signature) errors.push('eudi requires an owner_signature');
+    } else {
+      errors.push(`high assurance requires method "as_vouched" or "eudi", got "${method}"`);
+    }
+    if (disclose && typeof disclose.name !== 'string') errors.push('disclose.name must be a string');
+  } else {
+    errors.push(`assurance must be "low" or "high", got "${assurance as string}"`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * 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.
+ *
+ *  - low / no disclosure → "Sent by an AI agent via «operator»"
+ *  - high / as_vouched   → "Sent by an AI agent of «name», verified by «operator»"
+ *  - high / eudi         → "Sent by an AI agent of «name», identity verified (EUDI)"
+ *
+ * Punctuation is ASCII (comma, not em-dash) so the line survives header and
+ * plain-text encoding intact across email, calendar, and publishing channels.
+ * The leading verb ("Sent") is the default; presentation layers may swap it
+ * (e.g. the gateway uses "Published" for the publish profile).
+ *
+ * `operatorName` is the rendered AS operator (e.g. "Suveren") — never hardcode it
+ * upstream; a different operator self-vouches under its own name.
+ */
+export function deriveIdentityLine(
+  subject: Subject | undefined | null,
+  { operatorName }: { operatorName: string },
+): string {
+  const name = subject?.assurance === 'high' ? subject.disclose?.name : undefined;
+  if (!name) {
+    return `Sent by an AI agent via ${operatorName}`;
+  }
+  if (subject!.method === 'eudi') {
+    return `Sent by an AI agent of ${name}, identity verified (EUDI)`;
+  }
+  return `Sent by an AI agent of ${name}, verified by ${operatorName}`;
+}

package/src/index.ts

@@ -8,6 +8,7 @@ export * from './types';
 export * from './canonicalize';
 export * from './content-binding';
 export * from './intent-disclosure';
+export * from './identity';
 export * from './frame';
 export * from './attestation';
 export * from './gatekeeper';

package/src/types.ts

@@ -51,6 +51,14 @@ export interface AttestationPayload {
    * without invalidating the attestation signature (companion invariant C2).
    */
   intent_disclosure_hash?: string;
+  /**
+   * v0.6 (Identity Assurance) — optional signed overlay carrying the verified
+   * real-world identity of the Decision Owner(s), one entry per owner. Present
+   * only when identity is disclosed; an attestation with no `subjects` renders
+   * as `low` (pseudonymous, no name). See {@link Subject} and
+   * {@link deriveIdentityLine}.
+   */
+  subjects?: Subject[];
   /**
    * v0.4 — commitment mode chosen by the decision owner at attestation time.
    * - 'automatic': agent may invoke bounded tools without per-action review.
@@ -65,6 +73,37 @@ export interface AttestationPayload {
   expires_at: number;
 }
 
+/**
+ * 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.
+ *
+ * Two display levels (`assurance`): `low` discloses no name; `high` MAY disclose a
+ * name. At `high`, two trust roots: `as` (the AS operator vouches — valid only
+ * within its own domain) and `external` (an external eID such as EUDI — carries the
+ * owner's own signature, AS-independent). See review.md → "Identity Assurance".
+ */
+export interface Subject {
+  /** The Decision Owner DID this subject describes (matches an entry in resolved_owners). */
+  did: string;
+  /** `low` → no name shown; `high` → the name MAY be shown. */
+  assurance: 'low' | 'high';
+  /** How identity was established. */
+  method: 'self_declared' | 'as_vouched' | 'eudi';
+  /** Who vouches: `self` (owner's claim), `as` (operator), `external` (eID scheme). */
+  trust_root: 'self' | 'as' | 'external';
+  /** Verifier id — the AS operator (as_vouched) or the eID scheme (eudi). Required at `high`. */
+  verifier?: string;
+  /** Disclosed attributes. `name` present ONLY at `assurance:"high"` and when disclosure is on. */
+  disclose?: { name: string };
+  /** 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.
+   */
+  owner_signature?: string | null;
+}
+
 export interface Attestation {
   header: AttestationHeader;
   payload: AttestationPayload;