@greenlandai/sdk 0.1.0

package/index.js

@@ -0,0 +1,40 @@
+/**
+ * @greenlandai/sdk — unified SDK for the GreenlandAI ecosystem.
+ * Design contract: unified-greenlandai-sdk-design-v1-2026-06-10.md (v1.1).
+ * Supersedes-but-does-not-replace @enyalai/sdk v2.1.x (permanent coexistence, §5).
+ */
+import { Transport } from "./src/core/transport.js";
+import { EnyalSubmodule, ENYAL_BASE } from "./src/enyal.js";
+import { JoulepaiSubmodule, JOULEPAI_BASE } from "./src/joulepai.js";
+import { RareeaiSubmodule, RAREEAI_BASE } from "./src/rareeai.js";
+import { GldaiSubmodule, GLDAI_BASE } from "./src/gldai.js";
+
+export {
+  GreenlandAIError, AuthError, ScopeError, NotFoundError, ValidationError,
+  ConflictError, RateLimitError, ServerError, NetworkError,
+} from "./src/core/errors.js";
+export { ENFORCED, NOT_SUPPORTED, SAFE, IDEMPOTENCY_MAP } from "./src/core/idempotency.js";
+export * as crypto from "./src/core/crypto.js";
+
+export const VERSION = "0.1.0";
+
+export class Client {
+  /**
+   * @param {object} opts
+   * @param {string} [opts.apiKey] - eyl_ API key (primary for SDK consumers).
+   * @param {string} [opts.oauthToken] - ENYAL-issued OAuth JWT (web sessions).
+   * @param {object} [opts.logger] - console-shaped logger (console/winston/pino).
+   * @param {function} [opts.onRetry] / [opts.onTerminalFailure] / [opts.onAuthExpired]
+   * @param {object} [opts.metrics] - {count(name,v), histogram(name,v)} sink (OFF default).
+   */
+  constructor({ apiKey, oauthToken, logger, onRetry, onTerminalFailure, onAuthExpired,
+                metrics, fetchImpl,
+                enyalBaseUrl, joulepaiBaseUrl, rareeaiBaseUrl, gldaiBaseUrl } = {}) {
+    this._transport = new Transport({ apiKey, oauthToken, logger, onRetry,
+                                      onTerminalFailure, onAuthExpired, metrics, fetchImpl });
+    this.enyal = new EnyalSubmodule(this._transport, enyalBaseUrl || ENYAL_BASE);
+    this.joulepai = new JoulepaiSubmodule(this._transport, joulepaiBaseUrl || JOULEPAI_BASE);
+    this.rareeai = new RareeaiSubmodule(this._transport, rareeaiBaseUrl || RAREEAI_BASE);
+    this.gldai = new GldaiSubmodule(this._transport, gldaiBaseUrl || GLDAI_BASE);
+  }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@greenlandai/sdk",
+  "version": "0.1.0",
+  "description": "Unified SDK for the GreenlandAI ecosystem (ENYAL, JoulePAI, RAREEAI, GreenlandAI)",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "dist/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@scure/bip39": "^1.3.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.21.0"
+  },
+  "scripts": {
+    "build": "esbuild index.js --bundle --platform=node --format=cjs --external:@scure/bip39 --outfile=dist/index.cjs",
+    "test": "node --test test/"
+  }
+}

package/src/core/crypto.js

@@ -0,0 +1,301 @@
+/**
+ * Client-side cryptography (design §4.1.2-4.1.3).
+ * GF256/Shamir/P-256/AES-GCM primitives ported VERBATIM from the published
+ * @enyalai/sdk@2.1.0 artifact (package/enyal-client.js:22-199 + :217-291 — pure
+ * functions only; API-calling siblings live on client.enyal).
+ * BIP39 = NEW surface (@scure/bip39, locked per design §9 item 5 / P-DAY.22);
+ * decryptKnowledgeNode absorbed per AUDIT.6 / design v1.1 Edit 3.
+ */
+// GF(256) Arithmetic — identical to enyal/shamir.py
+// Generator = 3, irreducible polynomial = 0x11B (same as AES)
+// ────────────────────────────────────────────────────────────────
+
+const GF256_EXP = new Uint8Array(512);
+const GF256_LOG = new Uint8Array(256);
+
+(function initGF256() {
+    let x = 1;
+    for (let i = 0; i < 255; i++) {
+        GF256_EXP[i] = x;
+        GF256_LOG[x] = i;
+        let hi = x << 1;
+        if (hi & 0x100) hi ^= 0x11B;
+        x = hi ^ x;
+    }
+    for (let i = 255; i < 512; i++) {
+        GF256_EXP[i] = GF256_EXP[i - 255];
+    }
+})();
+
+function gf256Mul(a, b) {
+    if (a === 0 || b === 0) return 0;
+    return GF256_EXP[(GF256_LOG[a] + GF256_LOG[b]) % 255];
+}
+
+function gf256Inv(a) {
+    if (a === 0) throw new Error("Zero has no inverse in GF(256)");
+    return GF256_EXP[255 - GF256_LOG[a]];
+}
+
+/**
+ * Shamir Lagrange interpolation at x=0 for two shares.
+ * Each share: Uint8Array [index_byte, data_0, ..., data_31] = 33 bytes.
+ * Returns: Uint8Array of 32-byte reconstructed secret.
+ */
+function shamirCombine(share1, share2) {
+    if (share1.length !== 33 || share2.length !== 33) {
+        throw new Error("Share combination failed — each share must be 33 bytes");
+    }
+    const x1 = share1[0], x2 = share2[0];
+    if (x1 === 0 || x2 === 0 || x1 === x2) {
+        throw new Error("Share combination failed — invalid share indices");
+    }
+    const d = x1 ^ x2;
+    const dInv = gf256Inv(d);
+    const secret = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+        const y1 = share1[1 + i], y2 = share2[1 + i];
+        const num = gf256Mul(y1, x2) ^ gf256Mul(y2, x1);
+        secret[i] = gf256Mul(num, dInv);
+    }
+    return secret;
+}
+
+// ────────────────────────────────────────────────────────────────
+// Encoding Helpers
+// ────────────────────────────────────────────────────────────────
+
+function hexToBytes(hex) {
+    hex = hex.trim();
+    if (hex.length % 2 !== 0) throw new Error("Hex string has odd length");
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+    }
+    return bytes;
+}
+
+function bytesToHex(bytes) {
+    return Array.from(bytes).map(b => b.toString(16).padStart(2, "0")).join("");
+}
+
+function base64ToBytes(b64) {
+    const bin = atob(b64);
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+    return bytes;
+}
+
+// ────────────────────────────────────────────────────────────────
+// Crypto Helpers (Web Crypto API)
+// ────────────────────────────────────────────────────────────────
+
+/**
+ * HKDF-SHA256 matching enyal's bsv_memory._memory_kdf:
+ *   PRK = HMAC-SHA256(salt=zeros(32), IKM=shared_secret)
+ *   OKM = HMAC-SHA256(PRK, "joulepai-memory-v1" || 0x01)
+ */
+async function memoryKDF(sharedSecret) {
+    const salt = new Uint8Array(32);
+    const prkKey = await crypto.subtle.importKey("raw", salt, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const prk = new Uint8Array(await crypto.subtle.sign("HMAC", prkKey, sharedSecret));
+    const okmKey = await crypto.subtle.importKey("raw", prk, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const context = new TextEncoder().encode("joulepai-memory-v1");
+    const info = new Uint8Array(context.length + 1);
+    info.set(context);
+    info[context.length] = 0x01;
+    return new Uint8Array(await crypto.subtle.sign("HMAC", okmKey, info));
+}
+
+/**
+ * AES-256-GCM decrypt. On auth tag mismatch (wrong key/share), throws
+ * a user-friendly error instead of raw crypto exception.
+ */
+async function aesGcmDecrypt(keyBytes, iv, ciphertext, tag) {
+    const aesKey = await crypto.subtle.importKey("raw", keyBytes, { name: "AES-GCM" }, false, ["decrypt"]);
+    const ctWithTag = new Uint8Array(ciphertext.length + tag.length);
+    ctWithTag.set(ciphertext);
+    ctWithTag.set(tag, ciphertext.length);
+    try {
+        const plaintext = await crypto.subtle.decrypt(
+            { name: "AES-GCM", iv, tagLength: 128 },
+            aesKey, ctWithTag
+        );
+        return new Uint8Array(plaintext);
+    } catch (_) {
+        throw new Error(
+            "Share combination failed — invalid recovery phrase or share. " +
+            "Please verify your recovery phrase and try again."
+        );
+    }
+}
+
+/**
+ * P-256 point decompression (pure JS, no dependencies).
+ * Converts 33-byte compressed public key to 65-byte uncompressed.
+ */
+function decompressP256(compressed) {
+    if (compressed.length !== 33) throw new Error("Expected 33-byte compressed key");
+    const prefix = compressed[0];
+    if (prefix !== 0x02 && prefix !== 0x03) throw new Error("Invalid P-256 prefix");
+
+    const P = 0xffffffff00000001000000000000000000000000ffffffffffffffffffffffffn;
+    const A = P - 3n;
+    const B = 0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604bn;
+
+    let x = 0n;
+    for (let i = 1; i < 33; i++) x = (x << 8n) | BigInt(compressed[i]);
+
+    const rhs = (modPow(x, 3n, P) + ((A * x) % P + P) % P + B) % P;
+    const y = modPow(rhs, (P + 1n) / 4n, P);
+
+    const yIsOdd = (y & 1n) === 1n;
+    const wantOdd = prefix === 0x03;
+    const finalY = yIsOdd === wantOdd ? y : P - y;
+
+    const out = new Uint8Array(65);
+    out[0] = 0x04;
+    for (let i = 31; i >= 0; i--) { out[1 + i] = Number((x >> BigInt((31 - i) * 8)) & 0xFFn); }
+    for (let i = 31; i >= 0; i--) { out[33 + i] = Number((finalY >> BigInt((31 - i) * 8)) & 0xFFn); }
+    return out;
+}
+
+function modPow(base, exp, mod) {
+    let result = 1n;
+    base = ((base % mod) + mod) % mod;
+    while (exp > 0n) {
+        if (exp & 1n) result = (result * base) % mod;
+        exp >>= 1n;
+        base = (base * base) % mod;
+    }
+    return result;
+}
+
+// ────────────────────────────────────────────────────────────────
+// TIER 1 — Client-side (zero trust in ENYAL)
+// ────────────────────────────────────────────────────────────────
+
+/**
+ * 1. Request client-side disclosure materials from ENYAL.
+ *    Returns encrypted chunks + ECDH-encrypted custodial share + poseidon_key_hash.
+ *    No decryption on server. Customer share is NOT sent.
+ *
+ * @param {string} apiKey - ENYAL API key (eyl_...)
+ * @param {string} baseUrl - API base URL (e.g. "https://api.enyal.ai")
+ * @param {string[]} chunkIds - chunk IDs to disclose
+ * @param {string} purpose - disclosure purpose description
+export async function decryptCustodialShare(encryptedShare, customerPrivateKeyBytes, p256ScalarMul) {
+    const ephemPub = hexToBytes(encryptedShare.ephemeral_pubkey_hex);
+    const iv = hexToBytes(encryptedShare.iv_hex);
+    const tag = hexToBytes(encryptedShare.tag_hex);
+    const ct = base64ToBytes(encryptedShare.encrypted_share);
+
+    const sharedSecretX = await p256ScalarMul(customerPrivateKeyBytes, ephemPub);
+    const aesKey = await memoryKDF(sharedSecretX);
+    return aesGcmDecrypt(aesKey, iv, ct, tag);
+}
+
+/**
+ * 3. Combine shares and decrypt a chunk.
+ *    GF(256) Lagrange interpolation → reconstruct private key → ECDH → AES-GCM decrypt.
+ *    On wrong share: AES-GCM auth tag mismatch → clear error message.
+ *
+ * @param {Uint8Array} customerShare - 33-byte customer share (index + data)
+ * @param {Uint8Array} custodialShare - 33-byte custodial share (from decryptCustodialShare)
+ * @param {Object} chunk - chunk object from disclosure response (with encrypted_payload + encryption_metadata)
+ * @param {Function} p256ScalarMul - async (privKeyBytes, compressedPubKey) => Uint8Array(32)
+ * @returns {Promise<Uint8Array>} decrypted plaintext bytes
+ */
+export async function combineSharesAndDecrypt(customerShare, custodialShare, chunk, p256ScalarMul) {
+    const privateKey = shamirCombine(customerShare, custodialShare);
+    const ephemPub = hexToBytes(chunk.encryption_metadata.ecdh_public_key_hex);
+    const sharedSecretX = await p256ScalarMul(privateKey, ephemPub);
+    const aesKey = await memoryKDF(sharedSecretX);
+    const iv = hexToBytes(chunk.encryption_metadata.iv_hex);
+    const tag = hexToBytes(chunk.encryption_metadata.tag_hex);
+    const ct = base64ToBytes(chunk.encrypted_payload);
+    return aesGcmDecrypt(aesKey, iv, ct, tag);
+}
+
+/**
+ * 4. Verify share combination locally via WASM (78KB).
+ *    Runs content integrity hash of reconstructed key in browser — zero server calls.
+ *
+ * @param {Uint8Array} customerShare - 33-byte customer share
+ * @param {Uint8Array} custodialShare - 33-byte custodial share
+ * @param {string} poseidonKeyHash - 64-char hex of expected key hash
+ * @param {string} [wasmUrl] - URL to shamir_verify.js (default: /static/shamir_verify.js)
+ * @returns {Promise<{valid: boolean, reconstructed_hash: string, expected_hash: string}>}
+ */
+export async function verifyShareCombination(customerShare, custodialShare, poseidonKeyHash, wasmUrl) {
+    const moduleUrl = wasmUrl || "/static/shamir_verify.js";
+    const mod = await import(moduleUrl);
+    await mod.default(moduleUrl.replace(".js", ".wasm"));
+    const result = mod.verify_share_combination(
+        bytesToHex(customerShare),
+        bytesToHex(custodialShare),
+        poseidonKeyHash
+    );
+    return JSON.parse(result);
+}
+
+// ────────────────────────────────────────────────────────────────
+// TIER 2 — Proof server (trust ENYAL during proof generation)
+// ────────────────────────────────────────────────────────────────
+
+/**
+ * 5. Request a cryptographic share combination proof from ENYAL (Tier 2).
+ *    Customer sends their share to the server. ENYAL retrieves its custodial share,
+ *    generates a zero-knowledge proof via the proof server, then wipes both shares.
+ *
+ *    NOTE: This is NOT zero-knowledge to ENYAL. ENYAL sees the share during
+ *    proof generation. The proof is for third-party auditors.
+ *    For zero-trust verification, use Tier 1 (verifyShareCombination).
+ *    For zero-trust proof generation, use Tier 3 (self-hosted Rust binary).
+ *
+ * @param {string} apiKey - ENYAL API key
+ * @param {string} baseUrl - API base URL
+ * @param {string} customerShareHex - 66-char hex of customer share
+ * @param {string} [poseidonKeyHash] - optional, looked up from account if omitted
+ * @returns {Promise<Object>} proof + share_attestation
+ */
+
+// ── BIP39 primitive (design §4.1.2) ──
+import { mnemonicToSeedSync, validateMnemonic } from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english";
+import { ValidationError } from "./errors.js";
+
+export function deriveSharesFromMnemonic(mnemonicPhrase, passphrase = "") {
+  const norm = mnemonicPhrase.trim().split(/\s+/).join(" ");
+  if (!validateMnemonic(norm, wordlist)) {
+    throw new ValidationError(null, "Invalid BIP39 mnemonic (bad word or checksum)");
+  }
+  const seed = mnemonicToSeedSync(norm, passphrase); // Uint8Array(64), BIP39 standard
+  const customerShare = new Uint8Array(33);
+  customerShare[0] = 1; // share-index byte, 33-byte format per shamirCombine contract
+  customerShare.set(seed.slice(0, 32), 1);
+  return { seed, customerShare };
+}
+
+// ── Absorbed stray (AUDIT.6): knowledge-node field decryption ──
+// Verbatim port from local joulepai-sdk-js index.js:358-385.
+export async function decryptKnowledgeNode(node, keyBase64) {
+  const key = await crypto.subtle.importKey(
+    "raw", Uint8Array.from(atob(keyBase64), (c) => c.charCodeAt(0)),
+    { name: "AES-GCM" }, false, ["decrypt"]);
+  node.name = await _decryptNodeField(node.name, key);
+  node.summary = await _decryptNodeField(node.summary, key);
+  return node;
+}
+
+async function _decryptNodeField(b64, key) {
+  if (!b64) return "";
+  try {
+    const d = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+    if (d.length < 13) return b64;
+    const dec = await crypto.subtle.decrypt({ name: "AES-GCM", iv: d.slice(0, 12) }, key, d.slice(12));
+    return new TextDecoder().decode(dec);
+  } catch {
+    return b64;
+  }
+}

package/src/core/errors.js

@@ -0,0 +1,33 @@
+/** Typed error hierarchy (design §3.2) — same names as Python. */
+
+export class GreenlandAIError extends Error {
+  constructor(statusCode, detail, requestId = null, retryAfter = null) {
+    super(statusCode ? `${statusCode}: ${detail}` : String(detail));
+    this.name = this.constructor.name;
+    this.statusCode = statusCode;
+    this.detail = detail;
+    this.requestId = requestId;
+    this.retryAfter = retryAfter;
+  }
+}
+export class AuthError extends GreenlandAIError {}
+export class ScopeError extends GreenlandAIError {}
+export class NotFoundError extends GreenlandAIError {}
+export class ValidationError extends GreenlandAIError {}
+export class ConflictError extends GreenlandAIError {}
+export class RateLimitError extends GreenlandAIError {}
+export class ServerError extends GreenlandAIError {}
+export class NetworkError extends GreenlandAIError {
+  constructor(detail) { super(null, detail); }
+}
+
+export function errorForStatus(statusCode, detail, requestId = null, retryAfter = null) {
+  if (statusCode === 401) return new AuthError(statusCode, detail, requestId);
+  if (statusCode === 403) return new ScopeError(statusCode, detail, requestId);
+  if (statusCode === 404) return new NotFoundError(statusCode, detail, requestId);
+  if (statusCode === 400 || statusCode === 422) return new ValidationError(statusCode, detail, requestId);
+  if (statusCode === 409) return new ConflictError(statusCode, detail, requestId, retryAfter);
+  if (statusCode === 429) return new RateLimitError(statusCode, detail, requestId, retryAfter);
+  if (statusCode >= 500) return new ServerError(statusCode, detail, requestId);
+  return new GreenlandAIError(statusCode, detail, requestId);
+}

package/src/core/idempotency.js

@@ -0,0 +1,83 @@
+/**
+ * Single-source idempotency dispatch (design §3.3, (ar) lock — four wire classes).
+ * Extends the published @enyalai/sdk 2.1.0 pattern (package/enyal-client.js:306-318).
+ * Tiers reflect the §6 matrix POST-G1 (build log 2026-06-10). Mirrors Python
+ * greenlandai/_core/idempotency.py exactly — single conceptual map, two renderings,
+ * cross-checked by test category (b)/(c).
+ */
+import { randomUUID } from "node:crypto";
+
+export const ENFORCED = "ENFORCED";
+export const NOT_SUPPORTED = "NOT_SUPPORTED";
+export const SAFE = "SAFE";
+
+export const IDEMPOTENCY_MAP = {
+  // Class A — Pattern A body-PK
+  "POST /api/v1/archive":              { field: "client_chunk_id", placement: "body", tier: ENFORCED },
+  "POST /api/v1/timestamp":            { field: "client_chunk_id", placement: "body", tier: ENFORCED },
+  "POST /api/v1/agreement/create":     { field: "client_chunk_id", placement: "body", tier: ENFORCED },
+  "POST /api/v1/compliance/attest":    { field: "client_attestation_id", placement: "body", tier: ENFORCED },
+  // Class B — Pattern B body idempotency_key
+  "POST /api/v1/prove":                { field: "idempotency_key", placement: "body", tier: ENFORCED },
+  "POST /api/v1/prove-batch":          { field: "idempotency_key", placement: "body", tier: ENFORCED },
+  "POST /api/v1/prove/share-combination": { field: "idempotency_key", placement: "body", tier: ENFORCED },
+  "POST /api/v1/disclose":             { field: "idempotency_key", placement: "body", tier: ENFORCED },
+  "POST /api/v1/disclose/client-side": { field: "idempotency_key", placement: "body", tier: ENFORCED },
+  "POST /api/v1/message/send":         { field: "idempotency_key", placement: "body", tier: ENFORCED },
+  "POST /api/v1/provide":              { field: "idempotency_key", placement: "body", tier: ENFORCED },
+  "POST /api/v1/request":              { field: "idempotency_key", placement: "body", tier: ENFORCED },
+  "POST /api/v1/deliver/{match_id}":   { field: "idempotency_key", placement: "body", tier: ENFORCED },
+  "POST /api/v1/match/{match_id}/resolve": { field: "idempotency_key", placement: "body", tier: ENFORCED },
+  "POST /api/v1/marketplace/provide":  { field: "idempotency_key", placement: "body", tier: ENFORCED },
+  "POST /api/v1/marketplace/request":  { field: "idempotency_key", placement: "body", tier: ENFORCED },
+  "POST /api/v1/marketplace/deliver/{match_id}": { field: "idempotency_key", placement: "body", tier: ENFORCED },
+  "POST /api/v1/marketplace/match/{match_id}/resolve": { field: "idempotency_key", placement: "body", tier: ENFORCED },
+  // Class C — header key (metered gldai)
+  "GET /api/v1/companies":             { field: "X-Idempotency-Key", placement: "header", tier: ENFORCED },
+  "GET /api/v1/deposits":              { field: "X-Idempotency-Key", placement: "header", tier: ENFORCED },
+  "GET /api/v1/infrastructure":        { field: "X-Idempotency-Key", placement: "header", tier: ENFORCED },
+  "GET /api/v1/query":                 { field: "X-Idempotency-Key", placement: "header", tier: ENFORCED },
+  "GET /api/v1/projects":              { field: "X-Idempotency-Key", placement: "header", tier: ENFORCED },
+  "GET /api/v1/mapdata":               { field: "X-Idempotency-Key", placement: "header", tier: ENFORCED },
+  // Class D — transfer-class
+  "POST /wallet/transfer":      { field: "idempotency_key", placement: "body", tier: ENFORCED },
+  // G1 demotions / unenforced mutating endpoints — explicit NOT_SUPPORTED
+  "POST /wallet/fund":          { field: null, placement: null, tier: NOT_SUPPORTED },
+  "POST /api/v1/match/{match_id}/approve": { field: null, placement: null, tier: NOT_SUPPORTED },
+  "POST /api/v1/match/{match_id}/reject": { field: null, placement: null, tier: NOT_SUPPORTED },
+  "POST /api/v1/match/{match_id}/dispute": { field: null, placement: null, tier: NOT_SUPPORTED },
+  "POST /api/v1/match/{match_id}/extend-dispute": { field: null, placement: null, tier: NOT_SUPPORTED },
+  "POST /api/v1/oracle/confirm/{match_id}": { field: null, placement: null, tier: NOT_SUPPORTED },
+  "POST /api/v1/oracle/register":      { field: null, placement: null, tier: NOT_SUPPORTED },
+  "POST /api/v1/marketplace/match/{match_id}/approve": { field: null, placement: null, tier: NOT_SUPPORTED },
+  "POST /api/v1/marketplace/match/{match_id}/reject": { field: null, placement: null, tier: NOT_SUPPORTED },
+  "POST /api/v1/marketplace/match/{match_id}/dispute": { field: null, placement: null, tier: NOT_SUPPORTED },
+  "POST /api/v1/marketplace/match/{match_id}/extend-dispute": { field: null, placement: null, tier: NOT_SUPPORTED },
+  "POST /api/v1/knowledge/upgrade":    { field: null, placement: null, tier: NOT_SUPPORTED },
+  "POST /api/v1/memory/structured-query": { field: null, placement: null, tier: NOT_SUPPORTED },
+  "POST /api/v1/memory/content-query": { field: null, placement: null, tier: NOT_SUPPORTED },
+  "POST /api/v1/proof/queue":          { field: null, placement: null, tier: NOT_SUPPORTED },
+};
+
+export function lookup(method, pathTemplate) {
+  return IDEMPOTENCY_MAP[`${method.toUpperCase()} ${pathTemplate}`] ?? null;
+}
+
+/** Place the key at the correct wire position. Key resolved ONCE per call
+ *  invocation, stable across retries (template: enyal-client.js retry shape). */
+export function dispatch(method, pathTemplate, body, headers, idempotencyKey) {
+  const entry = lookup(method, pathTemplate);
+  if (!entry) {
+    return { body, headers, tier: method.toUpperCase() === "GET" ? SAFE : ENFORCED, resolvedKey: null };
+  }
+  if (entry.tier === NOT_SUPPORTED || !entry.field) {
+    return { body, headers, tier: entry.tier, resolvedKey: null };
+  }
+  const resolved = idempotencyKey || randomUUID();
+  if (entry.placement === "body") {
+    body = { ...(body || {}), [entry.field]: resolved };
+  } else if (entry.placement === "header") {
+    headers = { ...headers, [entry.field]: resolved };
+  }
+  return { body, headers, tier: entry.tier, resolvedKey: resolved };
+}

package/src/core/transport.js

@@ -0,0 +1,124 @@
+/**
+ * Shared transport: retry + auth + telemetry hooks (design §2, §3.1, §3.4).
+ * Retry semantics from the published 2.1.0 template (package/enyal-client.js:322-344):
+ * 3 retries, 500ms initial, 8s max, x2 backoff, 100-300ms jitter; retryable =
+ * network/5xx/429; Retry-After honored. Layered rule: NOT_SUPPORTED tier => no auto-retry.
+ */
+import { NetworkError, RateLimitError, ServerError, errorForStatus } from "./errors.js";
+import { NOT_SUPPORTED, dispatch } from "./idempotency.js";
+
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_INITIAL_DELAY = 500;
+const DEFAULT_MAX_DELAY = 8000;
+const DEFAULT_BACKOFF_FACTOR = 2;
+const DEFAULT_JITTER_MIN = 100;
+const DEFAULT_JITTER_MAX = 300;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function isRetryable(err) {
+  return err instanceof NetworkError || err instanceof RateLimitError || err instanceof ServerError;
+}
+
+const noopLogger = { debug() {}, info() {}, warn() {}, error() {} };
+
+export class Transport {
+  constructor({ apiKey, oauthToken, logger, onRetry, onTerminalFailure,
+                onAuthExpired, metrics, fetchImpl } = {}) {
+    if (!apiKey && !oauthToken) throw new Error("apiKey or oauthToken required");
+    this._credential = apiKey || oauthToken;
+    this.logger = logger || noopLogger;
+    this.onRetry = onRetry || null;
+    this.onTerminalFailure = onTerminalFailure || null;
+    this.onAuthExpired = onAuthExpired || null;
+    this.metrics = metrics || null; // §3.4 — OFF by default
+    this._fetch = fetchImpl || fetch;
+  }
+
+  async request(baseUrl, method, pathTemplate,
+                { pathParams = {}, body = null, params = null,
+                  idempotencyKey = null, retry = true,
+                  maxRetries = DEFAULT_MAX_RETRIES } = {}) {
+    // WS-2 P1 fix (audit (cn)): discriminate transport by credential type. eyl_ API keys → X-API-Key
+    // (matches the ENYAL server + published enyal-client.js:396; `Bearer eyl_...` 401s via the JWT
+    // branch); OAuth JWTs → Authorization: Bearer. Server three-method contract: docs/canonical/
+    // security-policy.md. Non-eyl_ credentials are treated as OAuth JWTs (Bearer).
+    let headers = this._credential.startsWith("eyl_")
+      ? { "X-API-Key": this._credential }
+      : { Authorization: `Bearer ${this._credential}` };
+    const d = dispatch(method, pathTemplate, body, headers, idempotencyKey);
+    body = d.body; headers = d.headers;
+    if (d.tier === NOT_SUPPORTED) retry = false; // §3.1 layered rule
+
+    let path = pathTemplate;
+    for (const [k, v] of Object.entries(pathParams)) path = path.replace(`{${k}}`, encodeURIComponent(v));
+    let url = `${baseUrl.replace(/\/+$/, "")}${path}`;
+    if (params) {
+      const qs = new URLSearchParams(
+        Object.fromEntries(Object.entries(params).filter(([, v]) => v != null)));
+      url += `?${qs}`;
+    }
+
+    let attempt = 0;
+    const t0 = Date.now();
+    for (;;) {
+      try {
+        const result = await this._once(method, url, headers, body);
+        this._count("sdk.requests"); this._hist("sdk.request.duration", (Date.now() - t0) / 1000);
+        if (result && result.duplicate === true) {
+          this._count("sdk.duplicates");
+          this.logger.info(`duplicate response (idempotent replay) ${method} ${path}`);
+        }
+        return result;
+      } catch (err) {
+        if (err.statusCode === 401 && this.onAuthExpired) this.onAuthExpired(err); // §2: surface, never auto-refresh
+        if (!retry || attempt >= maxRetries || !isRetryable(err)) {
+          if (this.onTerminalFailure) this.onTerminalFailure(err, attempt + 1);
+          this.logger.warn(`terminal failure ${method} ${path} after ${attempt + 1} attempt(s)`);
+          throw err;
+        }
+        let delay = Math.min(DEFAULT_INITIAL_DELAY * DEFAULT_BACKOFF_FACTOR ** attempt, DEFAULT_MAX_DELAY)
+          + DEFAULT_JITTER_MIN + Math.random() * (DEFAULT_JITTER_MAX - DEFAULT_JITTER_MIN);
+        if (err.retryAfter) delay = Math.max(delay, Number(err.retryAfter) * 1000);
+        attempt += 1;
+        this._count("sdk.retries");
+        if (this.onRetry) this.onRetry(attempt, delay, err);
+        this.logger.info(`retry ${attempt}/${maxRetries} ${method} ${path} in ${Math.round(delay)}ms`);
+        await sleep(delay);
+      }
+    }
+  }
+
+  async _once(method, url, headers, body) {
+    const redacted = { ...headers };
+    if ("Authorization" in redacted) redacted.Authorization = "[REDACTED]";
+    if ("X-API-Key" in redacted) redacted["X-API-Key"] = "[REDACTED]";
+    this.logger.debug(`request ${method} ${url} headers=${JSON.stringify(redacted)}`);
+    let resp;
+    try {
+      const opts = { method, headers: { ...headers } };
+      if (body != null) {
+        opts.headers["Content-Type"] = "application/json";
+        opts.body = JSON.stringify(body);
+      }
+      resp = await this._fetch(url, opts);
+    } catch (err) {
+      throw new NetworkError(String(err && err.message ? err.message : err));
+    }
+    const requestId = resp.headers?.get ? resp.headers.get("x-request-id") : null;
+    const ra = resp.headers?.get ? resp.headers.get("retry-after") : null;
+    const retryAfter = ra ? Number(ra) : null;
+    if (resp.status >= 400) {
+      let detail;
+      try { const data = await resp.json(); detail = data.detail ?? resp.statusText; }
+      catch { detail = resp.statusText; }
+      if (typeof detail === "object") detail = JSON.stringify(detail);
+      throw errorForStatus(resp.status, String(detail), requestId, retryAfter);
+    }
+    if (resp.status === 204) return null;
+    return resp.json();
+  }
+
+  _count(name) { if (this.metrics) this.metrics.count(name, 1); }
+  _hist(name, v) { if (this.metrics) this.metrics.histogram(name, v); }
+}