@tangle-network/agent-provider-tangle 0.14.0 → 0.14.1

package/README.md

@@ -195,6 +195,13 @@ const provider = createTangleProvider({
 })
 ```
 
+The provider stores the raw report in `ConfidentialAttestation.quote` through
+`encodeTangleConfidentialAttestationQuote`.
+The quote is a versioned canonical JSON object with base64url byte fields.
+Use `decodeTangleConfidentialAttestationQuote` to recover a report and reject
+legacy numeric-array quotes, unknown fields, malformed bytes, and oversized
+reports before verification.
+
 ## Environment observation
 
 `environment.observe()` returns the normalized `AgentEnvironmentObservation`.

package/dist/index.d.ts

@@ -4,4 +4,6 @@ export { createTangleProvider } from "./tangle-provider.js";
 export { defaultTangleSandboxCapabilities } from "./tangle-capabilities.js";
 export { createTangleWorkspaceBranching, supportsWorkspaceBranching, } from "./tangle-workspace-branching.js";
 export type { TangleWorkspaceBranchingOptions } from "./tangle-workspace-branching.js";
+export { decodeTangleConfidentialAttestationQuote, encodeTangleConfidentialAttestationQuote, MAX_TEE_EVIDENCE_BYTES, MAX_TEE_MEASUREMENT_BYTES, TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_KIND, TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_VERSION, } from "./tangle-confidential-attestation.js";
+export type { TangleConfidentialAttestationReport } from "./tangle-confidential-attestation.js";
 export { safeEndpointFromConnection } from "./tangle-observation.js";

package/dist/index.js

@@ -2,4 +2,5 @@ export * from "./tangle-types.js";
 export { createTangleProvider } from "./tangle-provider.js";
 export { defaultTangleSandboxCapabilities } from "./tangle-capabilities.js";
 export { createTangleWorkspaceBranching, supportsWorkspaceBranching, } from "./tangle-workspace-branching.js";
+export { decodeTangleConfidentialAttestationQuote, encodeTangleConfidentialAttestationQuote, MAX_TEE_EVIDENCE_BYTES, MAX_TEE_MEASUREMENT_BYTES, TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_KIND, TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_VERSION, } from "./tangle-confidential-attestation.js";
 export { safeEndpointFromConnection } from "./tangle-observation.js";

package/dist/tangle-confidential-attestation.d.ts

@@ -0,0 +1,31 @@
+import type { SandboxTeeAttestationReportLike } from "./tangle-types.js";
+/** Version of the canonical opaque quote carried by a confidential attestation. */
+export declare const TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_VERSION: 1;
+/** Kind discriminator prevents this codec from accepting another quote format. */
+export declare const TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_KIND: "tangle-sandbox-tee";
+/** Raw evidence bound before it can enter a portable attestation. */
+export declare const MAX_TEE_EVIDENCE_BYTES = 16384;
+/** Raw measurement bound before it can enter a portable attestation. */
+export declare const MAX_TEE_MEASUREMENT_BYTES = 256;
+/** Read-only report shape accepted by the quote encoder. */
+export interface TangleConfidentialAttestationReport {
+    readonly tee_type: string;
+    readonly evidence: readonly number[];
+    readonly measurement: readonly number[];
+    readonly timestamp: number;
+}
+/**
+ * Encode a Sandbox TEE report without decimal JSON byte arrays.
+ *
+ * The returned JSON uses a fixed key order and unpadded base64url byte fields.
+ * `undefined` means the report is not a valid bounded report or the quote does
+ * not fit the shared confidential-attestation field.
+ */
+export declare function encodeTangleConfidentialAttestationQuote(report: TangleConfidentialAttestationReport): string | undefined;
+/**
+ * Decode and canonicalize a provider quote.
+ *
+ * The parser rejects old numeric-array quotes, unknown fields, non-canonical
+ * JSON, malformed base64url, and reports outside the provider bounds.
+ */
+export declare function decodeTangleConfidentialAttestationQuote(quote: unknown): SandboxTeeAttestationReportLike | undefined;

package/dist/tangle-confidential-attestation.js

@@ -0,0 +1,165 @@
+import { CONTRACT_MAX_CONFIDENTIAL_ATTESTATION_QUOTE_LENGTH, } from "@tangle-network/agent-interface";
+/** Version of the canonical opaque quote carried by a confidential attestation. */
+export const TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_VERSION = 1;
+/** Kind discriminator prevents this codec from accepting another quote format. */
+export const TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_KIND = "tangle-sandbox-tee";
+/** Raw evidence bound before it can enter a portable attestation. */
+export const MAX_TEE_EVIDENCE_BYTES = 16_384;
+/** Raw measurement bound before it can enter a portable attestation. */
+export const MAX_TEE_MEASUREMENT_BYTES = 256;
+const MAX_TEE_TYPE_LENGTH = 64;
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/u;
+const QUOTE_KEYS = [
+    "version",
+    "kind",
+    "tee_type",
+    "evidence",
+    "measurement",
+    "timestamp",
+];
+/**
+ * Encode a Sandbox TEE report without decimal JSON byte arrays.
+ *
+ * The returned JSON uses a fixed key order and unpadded base64url byte fields.
+ * `undefined` means the report is not a valid bounded report or the quote does
+ * not fit the shared confidential-attestation field.
+ */
+export function encodeTangleConfidentialAttestationQuote(report) {
+    if (!validReportShape(report))
+        return undefined;
+    const document = {
+        version: TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_VERSION,
+        kind: TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_KIND,
+        tee_type: report.tee_type,
+        evidence: bytesToBase64url(report.evidence),
+        measurement: bytesToBase64url(report.measurement),
+        timestamp: report.timestamp,
+    };
+    const quote = JSON.stringify(document);
+    return quote.length <= CONTRACT_MAX_CONFIDENTIAL_ATTESTATION_QUOTE_LENGTH
+        ? quote
+        : undefined;
+}
+/**
+ * Decode and canonicalize a provider quote.
+ *
+ * The parser rejects old numeric-array quotes, unknown fields, non-canonical
+ * JSON, malformed base64url, and reports outside the provider bounds.
+ */
+export function decodeTangleConfidentialAttestationQuote(quote) {
+    if (typeof quote !== "string" ||
+        quote.length === 0 ||
+        quote.length > CONTRACT_MAX_CONFIDENTIAL_ATTESTATION_QUOTE_LENGTH) {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(quote);
+    }
+    catch {
+        return undefined;
+    }
+    const document = quoteDocument(parsed);
+    if (document === undefined)
+        return undefined;
+    const report = reportFromDocument(document);
+    if (report === undefined)
+        return undefined;
+    return encodeTangleConfidentialAttestationQuote(report) === quote
+        ? report
+        : undefined;
+}
+function validReportShape(report) {
+    if (!isPlainObject(report))
+        return false;
+    if (!hasExactKeys(report, ["tee_type", "evidence", "measurement", "timestamp"])) {
+        return false;
+    }
+    return (validTeeType(report.tee_type) &&
+        validBytes(report.evidence, MAX_TEE_EVIDENCE_BYTES) &&
+        validBytes(report.measurement, MAX_TEE_MEASUREMENT_BYTES) &&
+        Number.isSafeInteger(report.timestamp) &&
+        report.timestamp > 0);
+}
+function quoteDocument(value) {
+    if (!isPlainObject(value) || !hasExactKeys(value, QUOTE_KEYS))
+        return undefined;
+    const candidate = value;
+    const teeType = candidate.tee_type;
+    const evidenceValue = candidate.evidence;
+    const measurementValue = candidate.measurement;
+    const timestamp = candidate.timestamp;
+    if (candidate.version !== TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_VERSION ||
+        candidate.kind !== TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_KIND ||
+        !validTeeType(teeType) ||
+        typeof evidenceValue !== "string" ||
+        typeof measurementValue !== "string" ||
+        typeof timestamp !== "number" ||
+        !Number.isSafeInteger(timestamp) ||
+        timestamp <= 0) {
+        return undefined;
+    }
+    const evidence = base64urlToBytes(evidenceValue, MAX_TEE_EVIDENCE_BYTES);
+    const measurement = base64urlToBytes(measurementValue, MAX_TEE_MEASUREMENT_BYTES);
+    if (evidence === undefined || measurement === undefined)
+        return undefined;
+    return {
+        version: TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_VERSION,
+        kind: TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_KIND,
+        tee_type: teeType,
+        evidence: evidenceValue,
+        measurement: measurementValue,
+        timestamp,
+    };
+}
+function reportFromDocument(document) {
+    const evidence = base64urlToBytes(document.evidence, MAX_TEE_EVIDENCE_BYTES);
+    const measurement = base64urlToBytes(document.measurement, MAX_TEE_MEASUREMENT_BYTES);
+    if (evidence === undefined || measurement === undefined)
+        return undefined;
+    const report = {
+        tee_type: document.tee_type,
+        evidence: Array.from(evidence),
+        measurement: Array.from(measurement),
+        timestamp: document.timestamp,
+    };
+    return validReportShape(report) ? report : undefined;
+}
+function validTeeType(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= MAX_TEE_TYPE_LENGTH &&
+        value.trim() === value &&
+        !/[\u0000-\u001f\u007f]/u.test(value));
+}
+function validBytes(value, maxLength) {
+    return (Array.isArray(value) &&
+        value.length > 0 &&
+        value.length <= maxLength &&
+        value.every((byte) => Number.isInteger(byte) && byte >= 0 && byte <= 255));
+}
+function bytesToBase64url(bytes) {
+    return Buffer.from(Uint8Array.from(bytes)).toString("base64url");
+}
+function base64urlToBytes(value, maxLength) {
+    if (value.length === 0 || !BASE64URL_PATTERN.test(value))
+        return undefined;
+    const bytes = Buffer.from(value, "base64url");
+    if (bytes.length === 0 ||
+        bytes.length > maxLength ||
+        bytes.toString("base64url") !== value) {
+        return undefined;
+    }
+    return bytes;
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function hasExactKeys(value, expected) {
+    const keys = Object.keys(value);
+    return keys.length === expected.length && keys.every((key) => expected.includes(key));
+}

package/dist/tangle-workspace-branching.js

@@ -1,5 +1,6 @@
 import { ConfidentialAttestationSchema, ConfidentialExecutionRequestSchema, ForkedEnvironmentRefSchema, WorkspaceCheckpointRefSchema, WorkspaceCheckpointRequestSchema, WorkspaceCleanupAcknowledgementSchema, WorkspaceCleanupRequestSchema, WorkspaceForkRequestSchema, WorkspaceOperationLookupRequestSchema, WorkspaceCheckpointResultSchema, WorkspaceCheckpointLookupResultSchema, WorkspaceForkResultSchema, WorkspaceForkLookupResultSchema, canonicalCandidateDigest, confidentialExecutionVerified, sha256Bytes, } from "@tangle-network/agent-interface";
 import { awaitWithSignal, boundedIdentifier, boundedString, assertBoundedJson, MAX_LIST_RESULTS, MAX_STRING_LENGTH, SANDBOX_LIST_PAGE_SIZE, } from "./tangle-contract-safety.js";
+import { encodeTangleConfidentialAttestationQuote, MAX_TEE_EVIDENCE_BYTES, MAX_TEE_MEASUREMENT_BYTES, } from "./tangle-confidential-attestation.js";
 /**
  * Namespace used for provider recovery metadata.
  *
@@ -532,7 +533,7 @@ async function confidentialAttestationForChild(request, child, provider, verifie
         return undefined;
     }
     const measurement = sha256Bytes(Uint8Array.from(response.attestation.measurement));
-    const quote = encodeJson(response.attestation);
+    const quote = encodeTangleConfidentialAttestationQuote(response.attestation);
     if (quote === undefined)
         return undefined;
     let verifiedAt;
@@ -610,10 +611,10 @@ function validTeeReport(report) {
     return !!report &&
         safeString(report.tee_type) !== undefined &&
         Array.isArray(report.evidence) &&
-        report.evidence.length <= MAX_STRING_LENGTH &&
+        report.evidence.length <= MAX_TEE_EVIDENCE_BYTES &&
         report.evidence.every((value) => Number.isInteger(value) && value >= 0 && value <= 255) &&
         Array.isArray(report.measurement) &&
-        report.measurement.length <= MAX_STRING_LENGTH &&
+        report.measurement.length <= MAX_TEE_MEASUREMENT_BYTES &&
         report.measurement.every((value) => Number.isInteger(value) && value >= 0 && value <= 255) &&
         Number.isFinite(report.timestamp) &&
         report.timestamp > 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -83,11 +83,13 @@
     "dist/tangle-types.js",
     "dist/tangle-workspace-branching.d.ts",
     "dist/tangle-workspace-branching.js",
+    "dist/tangle-confidential-attestation.d.ts",
+    "dist/tangle-confidential-attestation.js",
     "README.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "^1.7.0"
+    "@tangle-network/agent-interface": "^1.7.1"
   },
   "peerDependencies": {
     "@tangle-network/sandbox": ">=0.33.1 <1.0.0"