twin3-sdk 0.2.12-pre-alpha → 0.2.14-pre-alpha

package/README.md

@@ -60,7 +60,14 @@ Twin3 SDK organizes all distributed primitives into seven clean, composable laye
 | **L4 Shield** | `twin3.shield` | Differential tampering defense, prompt injection filtering, and authorization guardrails. | `scan_text` / `scan_envelope` (T0–T3), `IntelEngine` (T1), `Ensemble` (T4), `diff_plans` / `authorize_execution` (T5), `MemoryGuard` |
 | **L5 Matrix** | `twin3.matrix` | High-density vector space topological mapping and semantic cosine matching. | `DenseVector256`, `feature_distance`, `HumanMatrixSchema`, `EnterpriseMatrixSchema` |
 | **L6 Settlement** | `twin3.settlement` | Signed-receipt verification for HTTP 402 gates, with externally supplied chain-finality and replay controls. | `PaymentDemand`, `PaymentReceipt`, `X402SettlementEngine` |
-| **L7 Governance** | `twin3.governance` | Immutable evidence trail, appeals, advisory reputation federation, provisional arbitration helper. | `EvidenceTrail`, `open_appeal` / `resolve_appeal`, `export_reputation` / `import_reputation`, `ArbitrationEngine` (experimental), `DisputeCase` (experimental) |
+| **L7 Governance** | `twin3.governance` | Immutable evidence trail, appeals, advisory reputation federation, provisional arbitration helper. | `EvidenceTrail` (experimental), `open_appeal` / `resolve_appeal`, `export_reputation` / `import_reputation`, `ArbitrationEngine` (experimental), `DisputeCase` (experimental) |
+
+L1 also exposes a candidate discovery evidence API for xAgent ID and xHuman ID. It normalizes owner-supplied CDN/server visits and Google Search Console generative AI search exports, then returns separate visit and impression summaries and a display-ready view model. See [the L1 evidence contract and interface presentation guidance](docs/architecture/L1-DISCOVERY-VISIT-EVIDENCE.md). These APIs do not collect private logs or establish visitor identity on their own.
+
+Python and Node support [explicit Matrix comparison profiles](docs/matrix-runtime-profiles.md),
+including weighted/masked cosine and structured coverage results. Node constructor
+coercions still differ; Node Inbox payment admission remains Python-only. Evidence
+trail is experimental until an actual consumer supplies durable integration evidence.
 
 `(experimental)` marks a capability whose row in [`tests/capability-inventory.json`](tests/capability-inventory.json) is not yet `available`: it is importable today and its surface may still change. Everything unmarked is `available`. A name written `Class.method` is a method, not a module export. Every name in this table is checked against a real public export by [`tests/test_readme_capability_claims.py`](tests/test_readme_capability_claims.py).
 
@@ -70,12 +77,17 @@ Twin3 SDK organizes all distributed primitives into seven clean, composable laye
 
 The primitives in `twin3-sdk` are extracted from the `twin3-team/agent-id` Inbox line (PRs #615–#642, merged 2026-09-03 → 2026-09-05; spec: `docs/architecture/inbox-module-spec.md` in that repo). What each layer inherited:
 
+The paths below describe historical source in the
+[Agent ID repository](https://github.com/twin3-team/agent-id/tree/main/agent_id/inbox),
+not the current SDK directory layout. See the [generated Node API reference](docs/node-api.md)
+for the installed package's public declarations.
+
 * **Envelope, KYA handshake, counterparty ladder** — `agent_id/inbox/{envelope,kya,counterparty}.py`: canonical-JSON signed envelopes with `authority:"none"`, the mutual Ed25519 challenge that binds a declared identity to a key, and the G0→G3 attention ladder keyed on the counterparty rather than the request.
 * **Task inbox and state machine** — `agent_id/inbox/state.py`: intake gate, review gate, rate limits, stale expiry, hash-chained audit.
 * **Shield T0–T5** — `agent_id/inbox/{shield,intel,classifier,plandiff,corpus}.py`: deterministic layers, URL/domain/hash intelligence, the T4 ensemble, plan diffing, and the corpus that publishes error rates.
 * **Settlement policy** — `agent_id/inbox/payments.py`: owner policy, signed quotes and receipts behind HTTP 402.
 * **Governance** — `agent_id/inbox/governance.py`: appeals, pardons, advisory reputation federation.
-* **Canonical Matrix Core**: High-density 256-Byte vector topological clustering powering 140k natural human personality profiles and industrial tolerance matching.
+* **Canonical Matrix Core**: 256-dimensional single-pair vector arithmetic and tolerance comparison. The SDK does not supply population clustering, a similarity index or a batch ranking engine.
 
 The 2026-09-05 sync also adds the **AI-era hardening** (mandatory T5, identity-cost tier caps, provenance-gated memory, rotation demotes, paid ≠ authorized). See `CHANGELOG.md`.
 
@@ -103,22 +115,22 @@ pip install -e /path/to/twin3-sdk
 * Any protocol or algorithm improvement in `twin3-sdk` is reflected in both applications in **0 milliseconds**.
 
 #### 2. Production Distribution
-`v0.2.12-pre-alpha` is the current release candidate: `0.2.12-pre-alpha` for npm and `0.2.12a0` for PyPI. Publication is pending. Consumers must pin the exact released version and lock its registry integrity; never use a mutable range for a cryptographic protocol dependency. This release stays pre-alpha. Marketplace or sales copy may offer it for evaluation; it is not a stable release, and the npm dist-tag is `next`, not `latest`.
+`v0.2.14-pre-alpha` is the current release candidate: `0.2.14-pre-alpha` for npm and `0.2.14a0` for PyPI. Publication is pending. Consumers must pin the exact released version and lock its registry integrity; never use a mutable range for a cryptographic protocol dependency. This release stays pre-alpha. Marketplace or sales copy may offer it for evaluation; it is not a stable release, and the npm dist-tag is `next`, not `latest`.
 
 `package.json` `engines` sets Node.js to `>=18` and does not set an npm engine. Any npm that can install a tarball can consume the package. Packing this repository was checked with npm 10 or newer; the stricter npm version in the release runbook applies only to Trusted Publishing.
 
 After publication, install the exact released version from the registry:
 
 ```bash
-npm install twin3-sdk@0.2.12-pre-alpha
-pip install twin3-sdk==0.2.12a0
+npm install twin3-sdk@0.2.14-pre-alpha
+pip install twin3-sdk==0.2.14a0
 ```
 
 For local evaluation, you can also use the packed npm tarball. Do not install from a git URL or a version range:
 
 ```bash
 npm pack --ignore-scripts
-npm install ./twin3-sdk-0.2.12-pre-alpha.tgz
+npm install ./twin3-sdk-0.2.14-pre-alpha.tgz
 ```
 
 ---
@@ -135,7 +147,7 @@ Agent ID consumes Twin3 SDK to execute the **5-Stage A2A Autonomous Commercial L
 
 ### 👤 Human ID (Personal Sovereignty Projection)
 Human ID consumes Twin3 SDK to empower natural individuals:
-1. **140,000 Real Personality Assets**: Computes high-density personality matching via `twin3.matrix` without risking underlying database schemas.
+1. **Personality Assets**: Uses `twin3.matrix` for single-pair vector comparisons. Population indexing, ranking throughput and storage remain product responsibilities.
 2. **Passkey WebAuthn Login**: Binds biometric secure enclaves to decentralized keys via `twin3.trust`.
 3. **Paid Inbox**: Protects individual inboxes against spam using `twin3.comm` and the signed-receipt adapter ($5 paywall threshold); the application supplies chain verification and shared replay state.
 4. **Sovereign Card**: Renders non-custodial credentials using `twin3.discovery`.

package/index.d.ts

@@ -1,3 +1,8 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+export interface JsonObject { [key: string]: JsonValue; }
+export type CryptoKeyInput = string | Buffer | import("node:crypto").KeyObject;
+
 export declare const AGENT_CARD_SCHEMA: "twin3-discovery-agent-card-v1";
 export declare const SOVEREIGN_CARD_SCHEMA: "twin3-discovery-sovereign-card-v1";
 
@@ -10,7 +15,7 @@ export interface Twin3AgentCard {
   public_key: string | null;
   capabilities: string[];
   endpoints: Record<string, string>;
-  pricing: Record<string, any>;
+  pricing: JsonObject;
   created_at: number;
   digest: string;
 }
@@ -59,7 +64,7 @@ export interface Twin3AgentCardInput {
   publicKey?: string | null;
   capabilities?: string[];
   endpoints?: Record<string, string>;
-  pricing?: Record<string, any>;
+  pricing?: JsonObject;
   createdAt?: number;
 }
 
@@ -72,15 +77,92 @@ export declare function createTwin3AgentCard(input: Twin3AgentCardInput): Twin3A
 export declare const createAgentCard: typeof createTwin3AgentCard;
 export declare function parseTwin3AgentCard(data: unknown, options?: { verify?: boolean }): Twin3AgentCard;
 export declare function parseSovereignCard(data: unknown, options?: { verify?: boolean }): SovereignCard;
-export declare function cardDigest(card: SovereignCard | Twin3AgentCard | Record<string, any>): string;
-export declare function verifyCardDigest(card: SovereignCard | Twin3AgentCard | Record<string, any>): string;
-export declare function inspectCardWire(card: SovereignCard | Twin3AgentCard | Record<string, any>): CardWireInspection;
-export declare function migrateCardToEmit(card: SovereignCard | Twin3AgentCard | Record<string, any>): SovereignCard | Twin3AgentCard;
+export declare function cardDigest(card: SovereignCard | Twin3AgentCard | JsonObject): string;
+export declare function verifyCardDigest(card: SovereignCard | Twin3AgentCard | JsonObject): string;
+export declare function inspectCardWire(card: SovereignCard | Twin3AgentCard | JsonObject, options?: { allowLegacy?: boolean }): CardWireInspection;
+export declare function migrateCardToEmit(card: SovereignCard | Twin3AgentCard | JsonObject): SovereignCard | Twin3AgentCard;
+
+export declare const VISIT_EVIDENCE_SCHEMA: "twin3-discovery-visit-evidence-v1";
+export declare const AI_EXPOSURE_SCHEMA: "twin3-discovery-ai-exposure-v1";
+export declare const DISCOVERY_SUMMARY_SCHEMA: "twin3-discovery-evidence-summary-v1";
+export declare const DISCOVERY_VIEW_SCHEMA: "twin3-discovery-evidence-view-v1";
+export declare class DiscoveryEvidenceError extends Error { code: string; }
+export interface DiscoveryVisitInput {
+  source: "cdn_log" | "server_log";
+  record_id: string;
+  source_digest: string;
+  observed_at: number;
+  path: string;
+  status: number;
+  method?: "GET" | "HEAD";
+  request_count?: number;
+  user_agent?: string;
+  host?: string;
+}
+export interface DiscoveryVisitEvidence {
+  schema: typeof VISIT_EVIDENCE_SCHEMA;
+  host: string;
+  path: string;
+  surface: "agent_card" | "website";
+  source: "cdn_log" | "server_log";
+  record_id: string;
+  source_digest: string;
+  observed_at: number;
+  request_count: number;
+  method: "GET" | "HEAD";
+  status: number;
+  provider: string | null;
+  bot: string | null;
+  evidence_level: "ua_claim" | "unclassified";
+  user_agent_digest: string;
+  digest: string;
+}
+export interface AiExposureInput {
+  source: "google_search_console_generative_ai_search";
+  report_digest: string;
+  date: string;
+  page: string;
+  impressions: number;
+}
+export interface AiExposureEvidence extends AiExposureInput {
+  schema: typeof AI_EXPOSURE_SCHEMA;
+  host: string;
+  /** SHA-256 of the complete canonical page URL, including query and fragment. */
+  page_digest: string;
+  evidence_level: "owner_supplied_platform_export";
+  digest: string;
+}
+export interface DiscoveryEvidenceSummary {
+  schema: typeof DISCOVERY_SUMMARY_SCHEMA;
+  host: string;
+  visits: { records: number; requests: number; successful: number; failed: number; agent_card_successful: number; agent_card_bot_claim_successful: number; by_bot_claim: Record<string, number>; by_path: Record<string, number>; by_day_utc: Record<string, number> };
+  google_ai_search: { records: number; impressions: number; by_date: Record<string, number> };
+  visit_digests: string[];
+  exposure_digests: string[];
+  digest: string;
+}
+export declare function normalizeDiscoveryVisit(row: DiscoveryVisitInput, options: { host: string }): DiscoveryVisitEvidence;
+export declare function normalizeAiExposure(row: AiExposureInput, options: { host: string }): AiExposureEvidence;
+export declare function summarizeDiscoveryEvidence(visits: DiscoveryVisitEvidence[], exposures: AiExposureEvidence[], options: { host: string }): DiscoveryEvidenceSummary;
+export interface DiscoveryEvidenceView {
+  schema: typeof DISCOVERY_VIEW_SCHEMA;
+  host: string;
+  summary_digest: string;
+  cards: Array<{ id: string; label_zh_tw: string; value: number | null; unit: "requests" | "impressions"; state: "ready" | "not_connected" | "no_imported_records"; evidence_level: "http_log" | "ua_claim" | "owner_supplied_platform_export" }>;
+  trends: Array<{ id: string; unit: "requests" | "impressions"; date_basis: "utc" | "report_date"; state: "ready" | "not_connected" | "no_imported_records"; points: Array<{ date: string; value: number }> }>;
+  bot_claims: Array<{ bot: string; requests: number }>;
+  paths: Array<{ path: string; requests: number }>;
+  evidence_labels_zh_tw: Record<string, string>;
+  state_labels_zh_tw: Record<"no_imported_records" | "not_connected", string>;
+  notice_zh_tw: string;
+  digest: string;
+}
+export declare function buildDiscoveryEvidenceView(summary: DiscoveryEvidenceSummary, options: { visitSourceStatus: "connected" | "not_connected"; googleAiSearchSourceStatus: "connected" | "not_connected" }): DiscoveryEvidenceView;
 
 export declare const DESCRIPTOR_CANONICALIZATION: "rfc8785";
 export declare const DESCRIPTOR_SIGNATURE_FIELDS: readonly ["signatures", "signatureStatus"];
 export interface DescriptorSignature { protected: string; signature: string; }
-export interface SignedDescriptor extends Record<string, any> { signatures: DescriptorSignature[]; signatureStatus: string; }
+export interface SignedDescriptor extends Record<string, unknown> { signatures: DescriptorSignature[]; signatureStatus: string; }
 export interface DescriptorVerification {
   status: "signed" | "unsigned";
   digest: string;
@@ -88,13 +170,13 @@ export interface DescriptorVerification {
   jku: string | null;
   protected: { alg: "EdDSA"; typ: string; kid: string; jku?: string } | null;
 }
-export declare function descriptorBody(document: Record<string, any>): Record<string, any>;
-export declare function descriptorBytes(document: Record<string, any>): Buffer;
-export declare function descriptorDigest(document: Record<string, any>): string;
-export declare function descriptorEtag(document: Record<string, any>): string;
-export declare function signDescriptor(document: Record<string, any>, privateKey: string | Buffer | import("node:crypto").KeyObject, options?: { kid?: string; jku?: string | null; typ?: string }): SignedDescriptor;
-export declare function unsignedDescriptor(document: Record<string, any>, reason?: string): SignedDescriptor;
-export declare function verifyDescriptor(document: Record<string, any>, publicKey: string | Buffer | import("node:crypto").KeyObject | null | undefined, options?: { expectedKid?: string | null; expectedJku?: string | null; allowUnsigned?: boolean }): DescriptorVerification;
+export declare function descriptorBody(document: Record<string, unknown>): Record<string, unknown>;
+export declare function descriptorBytes(document: Record<string, unknown>): Buffer;
+export declare function descriptorDigest(document: Record<string, unknown>): string;
+export declare function descriptorEtag(document: Record<string, unknown>): string;
+export declare function signDescriptor(document: Record<string, unknown>, privateKey: string | Buffer | import("node:crypto").KeyObject, options?: { kid?: string; jku?: string | null; typ?: string }): SignedDescriptor;
+export declare function unsignedDescriptor(document: Record<string, unknown>, reason?: string): SignedDescriptor;
+export declare function verifyDescriptor(document: Record<string, unknown>, publicKey: string | Buffer | import("node:crypto").KeyObject | null | undefined, options?: { expectedKid?: string | null; expectedJku?: string | null; allowUnsigned?: boolean }): DescriptorVerification;
 
 export declare const WELL_KNOWN_DOCUMENT_SCHEMA: "twin3-discovery-well-known-v1";
 export interface WellKnownProtocol {
@@ -104,7 +186,7 @@ export interface WellKnownProtocol {
   required?: string[];
   implementation_specific?: string[];
 }
-export interface WellKnownDocument extends Record<string, any> {
+export interface WellKnownDocument extends Record<string, unknown> {
   schema: string;
   host: string;
   did?: string;
@@ -112,8 +194,8 @@ export interface WellKnownDocument extends Record<string, any> {
   digest: string;
 }
 export declare function buildWellKnownDocument(host: string, protocol: WellKnownProtocol, fields: Record<string, any>, options?: { did?: boolean | string; schema?: string }): WellKnownDocument;
-export declare function validateWellKnownDocument(document: Record<string, any>): Required<WellKnownProtocol>;
-export declare function resolveDocumentPath(document: Record<string, any>, dotted: string): [boolean, any];
+export declare function validateWellKnownDocument(document: Record<string, unknown>): Required<WellKnownProtocol>;
+export declare function resolveDocumentPath(document: Record<string, unknown>, dotted: string): [boolean, unknown];
 
 export interface OwnerPolicyInput extends Record<string, any> {
   stranger_requires_payment?: unknown;
@@ -240,7 +322,7 @@ export interface CounterpartyTable {
   freeze(identity: CounterpartyIdentity, actor: string, reason: string, options?: { now?: number }): CounterpartyRow;
   unfreeze(identity: CounterpartyIdentity, actor: string, reason: string, options?: { now?: number }): CounterpartyRow;
   bindKey(identity: CounterpartyIdentity, binding: Record<string, any>, actor: string, reason: string,
-    options?: { ownerPublicKey?: any; now?: number }): CounterpartyRow;
+    options?: { ownerPublicKey?: CryptoKeyInput; now?: number }): CounterpartyRow;
   boundKey(identity: CounterpartyIdentity): [string, string] | null;
   bindWallet(identity: CounterpartyIdentity, walletAddress: string,
     options?: { actor?: string; reason?: string; now?: number }): CounterpartyRow;
@@ -294,10 +376,10 @@ export declare function openAppeal(table: CounterpartyTable, identity: Counterpa
 export declare function resolveAppeal(table: CounterpartyTable, appealId: string,
   decision: "uphold" | "overturn", actor: string, reason: string, options?: { now?: number }): Appeal;
 export declare function listAppeals(table: CounterpartyTable, options?: { status?: string }): Appeal[];
-export declare function exportReputation(table: CounterpartyTable, owner: string, ownerPrivateKey: any,
+export declare function exportReputation(table: CounterpartyTable, owner: string, ownerPrivateKey: CryptoKeyInput,
   options?: { now?: number; minStrikes?: number }): ReputationBundle;
 export declare function importReputation(table: CounterpartyTable, bundle: Record<string, any>,
-  peerPublicKey: any, actor: string, options?: { now?: number; weight?: number }): ReputationImport;
+  peerPublicKey: CryptoKeyInput, actor: string, options?: { now?: number; weight?: number }): ReputationImport;
 
 export declare const TIERS: string[];
 export declare const TIER_RANK: Record<string, number>;
@@ -311,7 +393,7 @@ export declare function createCounterpartyTable(params: {
   store: Record<string, any>;
   owner: string;
   now?: number | (() => number);
-  ownerPublicKey?: any;
+  ownerPublicKey?: CryptoKeyInput;
   legacyTierResolver?: (owner: string, key: string, snapshot: Record<string, any>) => string;
 }): CounterpartyTable;
 export declare function emptyCounterpartyStore(): { schema: string; owners: Record<string, any> };
@@ -330,13 +412,13 @@ export declare function issueOwnerAccessGrant(params: {
   grantEpoch: number;
   actor: string;
   reason: string;
-  ownerPrivateKey: any;
+  ownerPrivateKey: CryptoKeyInput;
   now?: number;
   grantId?: string;
 }): OwnerAccessGrant;
 export declare function verifyOwnerAccessGrant(params: {
   grant: Record<string, any>;
-  ownerPublicKey: any;
+  ownerPublicKey: CryptoKeyInput;
   owner: string;
   identity: CounterpartyIdentity;
   binding: Record<string, any>;
@@ -381,7 +463,7 @@ export interface A2AAgentCardSignature {
   header?: Record<string, unknown>;
 }
 export interface A2AJwks { keys: import("node:crypto").JsonWebKey[]; }
-export interface A2AAgentCard extends Record<string, any> {
+export interface A2AAgentCard extends Record<string, unknown> {
   name: string;
   description: string;
   version: string;
@@ -486,7 +568,62 @@ export declare class DenseVector256 {
   cosineDistance(other: DenseVector256): number;
   compositeToleranceDistance(other: DenseVector256): number;
   matchTolerance(other: DenseVector256, maxDistance?: number): boolean;
-}
+  compare(other: DenseVector256, options?: MatrixComparisonOptions): MatrixComparisonResult;
+}
+
+export declare const COMPARISON_SCHEMA: "twin3-matrix-comparison-v1";
+export declare const COMPARISON_PROFILE_SCHEMA: "twin3-matrix-comparison-profile-v1";
+export type MatrixFeaturePolicy = "numeric" | "bitmask_jaccard" | "exact_bucket" | "split_nibble";
+export interface MatrixComparisonOptions {
+  metric?: "cosine" | "composite_rms";
+  dimensionPolicies?: Record<number, MatrixFeaturePolicy>;
+  missingByte?: number | null;
+  weights?: number[] | null;
+  maxDistance?: number | null;
+  minCoverage?: number | null;
+  sourceDigest?: string | null;
+  projectionDigest?: string | null;
+  mappingReference?: string | null;
+}
+export interface MatrixComparisonProfileWire {
+  schema: typeof COMPARISON_PROFILE_SCHEMA;
+  layout: string;
+  registry_reference: string;
+  excluded_dimensions: number[];
+  unresolved_dimensions: number[];
+}
+export interface MatrixComparisonResult {
+  schema: typeof COMPARISON_SCHEMA;
+  status: "comparable" | "not_comparable" | "insufficient_coverage" | "metric_undefined";
+  reason: string | null;
+  distance: number | null;
+  match: boolean | null;
+  comparable_dimensions: number;
+  eligible_weight: number;
+  requested_weight: number;
+  coverage: number | null;
+  metric: "cosine" | "composite_rms";
+  policy_version: "l5-rms-v1";
+  source_digest: string | null;
+  projection_digest: string | null;
+  mapping_reference: string | null;
+  profile?: MatrixComparisonProfileWire;
+}
+export declare class ComparisonProfile {
+  readonly layout: string;
+  readonly registryReference: string;
+  readonly excluded: readonly number[];
+  readonly unresolved: readonly number[];
+  constructor(options: { layout: string; registryReference: string; excluded?: number[]; unresolved?: number[] });
+  comparableDimensions(): number[];
+  defaultWeights(): number[];
+  resolveWeights(weights?: number[] | null): number[];
+  assertLayout(aLayout: string, bLayout: string): void;
+  compare(a: DenseVector256, b: DenseVector256, options: MatrixComparisonOptions & { aLayout: string; bLayout: string }): MatrixComparisonResult;
+  toDict(): MatrixComparisonProfileWire;
+}
+export declare function humanComparisonProfile(registryReference: string, unresolved?: number[]): ComparisonProfile;
+export declare function featureDistance(a: number, b: number, policy?: MatrixFeaturePolicy, missing?: number | null): number;
 
 export interface HumanMatrixQuadrantMap {
   physical: [number, number];
@@ -572,6 +709,41 @@ export declare function issuePasskeyChallenge(params: {
   expires_at: number;
 }>;
 
+export interface PasskeyRegistrationInput {
+  challenge: string;
+  credentialId: string;
+  clientDataJson: string;
+  attestationObject: string;
+  expectedOrigin: string;
+  expectedRpId: string;
+  requireUserVerification?: boolean;
+}
+export interface PasskeyRegistrationResult {
+  readonly valid: true;
+  readonly credential_id: string;
+  readonly public_key_pem: string;
+  readonly algorithm: -7;
+  readonly rp_id: string;
+  readonly origin: string;
+  readonly sign_count: number;
+  readonly user_present: true;
+  readonly user_verified: boolean;
+  readonly backup_eligible: boolean;
+  readonly backup_state: boolean;
+  readonly attestation_format: "none";
+}
+export type PasskeyRegistrationErrorCode =
+  | "registration_input_invalid" | "registration_context_invalid"
+  | "registration_client_data_invalid" | "registration_challenge_mismatch"
+  | "registration_origin_mismatch" | "registration_attestation_invalid"
+  | "registration_rp_mismatch" | "registration_flags_invalid"
+  | "registration_credential_mismatch" | "registration_key_invalid";
+export declare class PasskeyRegistrationError extends Error {
+  constructor(code?: PasskeyRegistrationErrorCode);
+  readonly code: PasskeyRegistrationErrorCode;
+}
+export declare function verifyPasskeyRegistration(input: PasskeyRegistrationInput): Readonly<PasskeyRegistrationResult>;
+
 export declare function verifyPasskeyAssertion(params: {
   challenge: string;
   clientDataJson: string;
@@ -640,7 +812,7 @@ export declare function verifyPasskeyAssertionWithStores(params: {
   challengeStore: ChallengeStore;
 }): Promise<ReturnType<typeof verifyPasskeyAssertion> & { user_id: string }>;
 
-export declare function keyId(publicKey: any): string;
+export declare function keyId(publicKey: CryptoKeyInput): string;
 
 export interface KyaIdentity {
   kind: string;
@@ -684,7 +856,7 @@ export declare function createKyaChallenge(params: {
   now?: number;
   ttlSeconds?: number;
 }): KyaChallenge;
-export declare function verifyOwnerSignature(challenge: KyaChallenge, ownerPublicKey: any): true;
+export declare function verifyOwnerSignature(challenge: KyaChallenge, ownerPublicKey: CryptoKeyInput): true;
 export declare function challengeSignaturePayload(challenge: KyaChallenge): Uint8Array;
 export declare function exportEd25519PublicKey(publicKey: string | object): string;
 export declare function verifyKyaChallenge(params: {
@@ -855,8 +1027,8 @@ export declare function buildEnvelope(params: {
   ttlSeconds?: number;
 }): Envelope;
 
-export declare function signEnvelope(envelope: Envelope, privateKey: any): Envelope;
-export declare function verifyEnvelopeSignature(envelope: Envelope, publicKey: any, expectedKeyId?: string): true;
+export declare function signEnvelope(envelope: Envelope, privateKey: CryptoKeyInput): Envelope;
+export declare function verifyEnvelopeSignature(envelope: Envelope, publicKey: CryptoKeyInput, expectedKeyId?: string): true;
 
 export declare function scanText(text: string, options?: { source?: string; now?: number }): ShieldVerdict;
 
@@ -1126,13 +1298,13 @@ export declare function issueReceipt(params: {
   identity: { kind: string; value: string };
   quote: Record<string, any>;
   reference: string;
-  ownerPrivateKey: any;
+  ownerPrivateKey: CryptoKeyInput;
   now?: number;
   receiptId?: string;
 }): SettlementReceipt;
 export declare function verifyReceipt(params: {
   receipt: Record<string, any>;
-  ownerPublicKey: any;
+  ownerPublicKey: CryptoKeyInput;
   owner: string;
   identity: { kind: string; value: string };
   quote?: Record<string, any> | null;
@@ -1292,7 +1464,7 @@ export interface CounterpartyAgent {
   keyId: string;
   routes: Record<"challenge" | "complete" | "submit" | "quote" | "declaration", string>;
   publicKey(format?: "compact" | "pem" | "multibase"): string;
-  answerChallenge(challenge: KyaChallenge, options?: { ownerPublicKey?: any; signPayload?: string }): ChallengeAnswer;
+  answerChallenge(challenge: KyaChallenge, options?: { ownerPublicKey?: CryptoKeyInput; signPayload?: string }): ChallengeAnswer;
   buildEnvelope(kind: Envelope["kind"], payload: Record<string, any>, options?: { ttlSeconds?: number; now?: number }): Envelope;
   signEnvelope(envelope: Envelope): Envelope;
   envelope(kind: Envelope["kind"], payload: Record<string, any>, options?: { ttlSeconds?: number; now?: number }): Envelope;
@@ -1305,7 +1477,7 @@ export declare function createCounterpartyAgent(params: {
   identity: Identity;
   keyPath?: string;
   privateKeyPem?: string;
-  privateKey?: any;
+  privateKey?: import("node:crypto").KeyObject;
   now?: () => number;
   legacySchemas?: boolean;
   routes?: Partial<CounterpartyAgent["routes"]>;
@@ -1320,8 +1492,8 @@ export declare function createRelayTransport(params: {
 export declare function createChallenge(params: {
   owner: string;
   identity: Identity;
-  counterpartyPublicKey: any;
-  ownerPrivateKey: any;
+  counterpartyPublicKey: CryptoKeyInput;
+  ownerPrivateKey: CryptoKeyInput;
   now?: number;
   ttlSeconds?: number;
   legacySchemas?: boolean;
@@ -1329,8 +1501,8 @@ export declare function createChallenge(params: {
 
 export declare function verifyChallengeAnswer(challenge: KyaChallenge, signature: string, options?: { now?: number }): true;
 export declare function envelopeDigest(envelope: Envelope): string;
-export declare function loadPublicKey(value: any): any;
-export declare function exportPublicKey(publicKey: any, format?: "compact" | "pem" | "multibase"): string;
+export declare function loadPublicKey(value: CryptoKeyInput): import("node:crypto").KeyObject;
+export declare function exportPublicKey(publicKey: CryptoKeyInput, format?: "compact" | "pem" | "multibase"): string;
 export declare const INBOX_ROUTES: CounterpartyAgent["routes"];
 
 export declare const TASK_STORE_SCHEMA: "twin3-comm-task-store-v1";
@@ -1523,3 +1695,27 @@ export declare namespace experimentalTaskInbox {
     expire(input: { principal: unknown; taskId: string; expectedVersion: number; operationId: string; reason: string }): Promise<InboxTask>;
   }
 }
+
+export interface ExternalEd25519Signer {
+  publicKey: string;
+  sign(bytes: Uint8Array, signal: AbortSignal): Promise<string> | string;
+}
+export interface ExternalSignerOptions {
+  now?: number;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+export type ExternalSignerErrorCode = "external_signer_input_invalid" | "external_signer_unavailable"
+  | "external_signer_aborted" | "external_signer_timeout" | "external_signer_signature_invalid" | "external_signer_expired";
+export declare class ExternalSignerError extends Error {
+  readonly code: ExternalSignerErrorCode;
+  constructor(code: ExternalSignerErrorCode);
+}
+export declare function createKyaChallengeWithSigner(params: ExternalSignerOptions & {
+  owner: string; identity: KyaIdentity; counterpartyPublicKey: string; signer: ExternalEd25519Signer;
+  ttlSeconds?: number;
+}): Promise<Readonly<KyaChallenge>>;
+export declare function signDelegationWithSigner(delegation: Record<string, unknown>, signer: ExternalEd25519Signer,
+  options?: ExternalSignerOptions): Promise<Readonly<Record<string, unknown>>>;
+export declare function signEnvelopeWithSigner(envelope: Envelope, signer: ExternalEd25519Signer,
+  options?: ExternalSignerOptions): Promise<Readonly<Envelope>>;

package/js/comm/counterparty.js

@@ -345,7 +345,15 @@ function createRelayTransport({ serviceOrigin, accessToken, fetch: fetcher = glo
     const token = typeof accessToken === "function" ? await accessToken() : accessToken;
     const headers = { "content-type": "application/json" };
     if (token) headers.authorization = "Bearer " + token;
-    const response = await fetcher(origin + pathname, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+    const response = await fetcher(origin + pathname, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      redirect: "manual",
+    });
+    if (response.type === "opaqueredirect" || (response.status >= 300 && response.status < 400)) {
+      throw sdkError("inbox_redirect_forbidden");
+    }
     const payload = await response.json();
     if (!response.ok || payload.ok === false) {
       const error = sdkError(payload && payload.error ? payload.error : `inbox_http_${response.status}`);

package/js/comm.d.ts

@@ -0,0 +1,66 @@
+export {
+  ACCESS_GRANT_SCHEMA,
+  COUNTERPARTY_RECORD_SCHEMA,
+  COUNTERPARTY_STORE_SCHEMA,
+  ChallengeAnswer,
+  CounterpartyAgent,
+  CounterpartyAuditEntry,
+  CounterpartyIdentity,
+  CounterpartyRow,
+  CounterpartyTable,
+  CryptoKeyInput,
+  DEFAULT_RATE_LIMIT,
+  DEFAULT_RATE_WINDOW,
+  Envelope,
+  FREEZE_STRIKES,
+  INBOX_ROUTES,
+  Identity,
+  IdentityRequired,
+  InboxTransport,
+  IntakeRejected,
+  KyaChallenge,
+  KyaIdentity,
+  NONCE_RETENTION,
+  OwnerAccessGrant,
+  REPUTATION_HALF_LIFE_SECONDS,
+  STALE_AFTER,
+  STATES,
+  ShieldVerdict,
+  TASK_EXPORT_SCHEMA,
+  TASK_SCHEMA,
+  TASK_STORE_SCHEMA,
+  TERMINAL,
+  TIERS,
+  TIER_POLICY_VERSION,
+  TIER_RANK,
+  TRANSITIONS,
+  TaskInbox,
+  TaskInboxOptions,
+  TaskInboxTask,
+  TierTransitionError,
+  TransitionError,
+  buildEnvelope,
+  counterpartyKey,
+  createChallenge,
+  createCounterpartyAgent,
+  createCounterpartyTable,
+  createRelayTransport,
+  decayReputation,
+  emptyCounterpartyStore,
+  emptyTaskStore,
+  envelopeDigest,
+  experimentalTaskInbox,
+  exportPublicKey,
+  exportTask,
+  issueOwnerAccessGrant,
+  loadPublicKey,
+  maxTierFor,
+  normalizeCounterpartyStore,
+  normalizeTaskStore,
+  signEnvelope,
+  taskTrustLine,
+  verifyChallengeAnswer,
+  verifyEnvelopeSignature,
+  verifyOwnerAccessGrant,
+  verifyOwnerSignature,
+} from "../index";

package/js/comm.js

@@ -0,0 +1,53 @@
+"use strict";
+const impl = require("./internal/comm.js");
+
+module.exports = {
+  TaskInbox: impl.TaskInbox,
+  IntakeRejected: impl.IntakeRejected,
+  TransitionError: impl.TransitionError,
+  STATES: impl.STATES,
+  TRANSITIONS: impl.TRANSITIONS,
+  TERMINAL: impl.TERMINAL,
+  STALE_AFTER: impl.STALE_AFTER,
+  NONCE_RETENTION: impl.NONCE_RETENTION,
+  DEFAULT_RATE_LIMIT: impl.DEFAULT_RATE_LIMIT,
+  DEFAULT_RATE_WINDOW: impl.DEFAULT_RATE_WINDOW,
+  TASK_SCHEMA: impl.TASK_SCHEMA,
+  TASK_STORE_SCHEMA: impl.TASK_STORE_SCHEMA,
+  emptyTaskStore: impl.emptyTaskStore,
+  normalizeTaskStore: impl.normalizeTaskStore,
+  experimentalTaskInbox: impl.experimentalTaskInbox,
+  buildEnvelope: impl.buildEnvelope,
+  signEnvelope: impl.signEnvelope,
+  verifyEnvelopeSignature: impl.verifyEnvelopeSignature,
+  createCounterpartyAgent: impl.commCounterparty.createCounterpartyAgent,
+  createRelayTransport: impl.commCounterparty.createRelayTransport,
+  createChallenge: impl.commCounterparty.createChallenge,
+  verifyOwnerSignature: impl.commCounterparty.verifyOwnerSignature,
+  verifyChallengeAnswer: impl.commCounterparty.verifyChallengeAnswer,
+  envelopeDigest: impl.commCounterparty.envelopeDigest,
+  loadPublicKey: impl.commCounterparty.loadPublicKey,
+  exportPublicKey: impl.commCounterparty.exportPublicKey,
+  INBOX_ROUTES: impl.commCounterparty.ROUTES,
+  TASK_EXPORT_SCHEMA: impl.TASK_EXPORT_SCHEMA,
+  exportTask: impl.exportTask,
+  taskTrustLine: impl.taskTrustLine,
+  ACCESS_GRANT_SCHEMA: impl.ACCESS_GRANT_SCHEMA,
+  TIER_POLICY_VERSION: impl.TIER_POLICY_VERSION,
+  counterpartyKey: impl.counterpartyKey,
+  maxTierFor: impl.maxTierFor,
+  issueOwnerAccessGrant: impl.issueOwnerAccessGrant,
+  verifyOwnerAccessGrant: impl.verifyOwnerAccessGrant,
+  TIERS: impl.TIERS,
+  TIER_RANK: impl.TIER_RANK,
+  COUNTERPARTY_STORE_SCHEMA: impl.COUNTERPARTY_STORE_SCHEMA,
+  COUNTERPARTY_RECORD_SCHEMA: impl.COUNTERPARTY_RECORD_SCHEMA,
+  REPUTATION_HALF_LIFE_SECONDS: impl.REPUTATION_HALF_LIFE_SECONDS,
+  FREEZE_STRIKES: impl.FREEZE_STRIKES,
+  TierTransitionError: impl.TierTransitionError,
+  IdentityRequired: impl.IdentityRequired,
+  createCounterpartyTable: impl.createCounterpartyTable,
+  emptyCounterpartyStore: impl.emptyCounterpartyStore,
+  normalizeCounterpartyStore: impl.normalizeCounterpartyStore,
+  decayReputation: impl.decayReputation,
+};