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

package/README.md

@@ -1,19 +1,19 @@
 # @tangle-network/agent-provider-tangle
 
 Wraps `@tangle-network/sandbox` as an `AgentEnvironmentProvider`.
-The peer range is `>=0.33.1 <1.0.0`, and this package is developed and tested against 0.33.1.
-The floor is 0.33.1 because workspace branching uses the keyed snapshot, fork,
+The peer range is `>=0.34.0 <1.0.0`, and this package is developed and tested against 0.34.3.
+The floor is 0.34.0 because workspace branching uses the keyed snapshot, fork,
 lookup, and cleanup operations added to that SDK.
 The provider fails closed when the configured backend or its catalog entry cannot be read.
 Newer SDKs may also provide `getBackend()` as a lookup over the same catalog.
 
 ```ts
-import { Sandbox } from '@tangle-network/sandbox'
-import { createTangleProvider } from '@tangle-network/agent-provider-tangle'
+import { Sandbox } from "@tangle-network/sandbox";
+import { createTangleProvider } from "@tangle-network/agent-provider-tangle";
 
 const provider = createTangleProvider({
   client: new Sandbox({ apiKey: process.env.TANGLE_API_KEY }),
-})
+});
 ```
 
 Detached dispatch returns the immutable Sandbox execution receipt in `controlRef`.
@@ -43,16 +43,16 @@ One provider reaches deployments of different ages, which is why the environment
 
 Each deployment flag this adapter reads gates the claims it backs, and no flag is read that gates nothing:
 
-| Deployment flag | Claims it gates |
-| --- | --- |
-| `dispatch.runControlRef` | `streaming.detach`, `streaming.turnIdempotency`, `sessions.continue`, `retainedControl`, `session.cancelRun` |
+| Deployment flag                   | Claims it gates                                                                                              |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `dispatch.runControlRef`          | `streaming.detach`, `streaming.turnIdempotency`, `sessions.continue`, `retainedControl`, `session.cancelRun` |
 | `dispatch.executionIdOnAdmission` | `streaming.detach`, `streaming.turnIdempotency`, `sessions.continue`, `retainedControl`, `session.cancelRun` |
-| `cancel.canonicalRunCancellation` | `sessions.continue`, `retainedControl`, `session.cancelRun` |
-| `cancel.digestBound` | `sessions.continue`, `retainedControl`, `session.cancelRun` |
-| `cancel.idempotent` | `sessions.continue`, `retainedControl`, `session.cancelRun` |
-| `runs.eventReplay` | `streaming.replay`, `sessions.continue`, `retainedControl`, `session.cancelRun` |
-| `runs.executionScopedStatus` | `sessions.continue`, `retainedControl`, `session.cancelRun` |
-| `interactions.responseDedupe` | `interactions`, `environment.respondToInteraction`, `session.respondToInteraction` |
+| `cancel.canonicalRunCancellation` | `sessions.continue`, `retainedControl`, `session.cancelRun`                                                  |
+| `cancel.digestBound`              | `sessions.continue`, `retainedControl`, `session.cancelRun`                                                  |
+| `cancel.idempotent`               | `sessions.continue`, `retainedControl`, `session.cancelRun`                                                  |
+| `runs.eventReplay`                | `streaming.replay`, `sessions.continue`, `retainedControl`, `session.cancelRun`                              |
+| `runs.executionScopedStatus`      | `sessions.continue`, `retainedControl`, `session.cancelRun`                                                  |
+| `interactions.responseDedupe`     | `interactions`, `environment.respondToInteraction`, `session.respondToInteraction`                           |
 
 Detached dispatch carries the caller's exact reference and refuses a receipt that does not name the execution back, so it needs both `dispatch` flags and a session handle to reach the run through.
 `sessions.continue`, `retainedControl`, and `session.cancelRun` need every flag in the table, because the capability schema refuses a partial retained-control block and each identity rests on its own flag.
@@ -70,19 +70,19 @@ The claim and the two methods stand or fall together.
 It is offered on the environment and on a session handle; the environment routes the command to the session its binding names.
 The command carries only the answer the caller supplied. No field is filled in on the caller's behalf, and an answer the outstanding ask's spec rejects is refused with the field named.
 
-| Result | Acknowledgement status |
-| --- | --- |
-| The deployment recorded and delivered the response | `accepted` |
-| The deployment already holds this exact response | `already_resolved_same` |
+| Result                                                        | Acknowledgement status                                           |
+| ------------------------------------------------------------- | ---------------------------------------------------------------- |
+| The deployment recorded and delivered the response            | `accepted`                                                       |
+| The deployment already holds this exact response              | `already_resolved_same`                                          |
 | The deployment already holds a different response for the ask | `already_resolved_different`, message naming the recorded digest |
-| The command names another provider, environment, or session | `binding_mismatch` |
-| The deployment refuses the binding | `binding_mismatch` |
-| The ask is unknown to the deployment | `unknown_interaction` |
-| The session is unknown to the deployment | `unknown_run` |
-| The ask left the outstanding set on a deadline | `expired` |
-| The ask's spec rejects the answer | `invalid_response`, message naming each field |
-| The response is recorded and delivery is unconfirmed | `transport_failure`, `retryable: true` |
-| The request did not reach the route | `transport_failure`, `retryable: true` |
+| The command names another provider, environment, or session   | `binding_mismatch`                                               |
+| The deployment refuses the binding                            | `binding_mismatch`                                               |
+| The ask is unknown to the deployment                          | `unknown_interaction`                                            |
+| The session is unknown to the deployment                      | `unknown_run`                                                    |
+| The ask left the outstanding set on a deadline                | `expired`                                                        |
+| The ask's spec rejects the answer                             | `invalid_response`, message naming each field                    |
+| The response is recorded and delivery is unconfirmed          | `transport_failure`, `retryable: true`                           |
+| The request did not reach the route                           | `transport_failure`, `retryable: true`                           |
 
 A refusal is never reported as a success, and a recorded response whose delivery the deployment does not confirm is never reported as `accepted`.
 
@@ -150,24 +150,24 @@ Clean branch resources before deleting the source or use a platform reaper.
 import {
   workspaceCheckpointRequestDigest,
   workspaceForkRequestDigest,
-} from '@tangle-network/agent-interface'
+} from "@tangle-network/agent-interface";
 
 const checkpoint = await environment.workspaceBranching?.checkpoint({
   source: exactRun,
-  idempotencyKey: 'checkpoint-before-analysis',
+  idempotencyKey: "checkpoint-before-analysis",
   requestDigest: workspaceCheckpointRequestDigest({ source: exactRun }),
-})
+});
 
-if (checkpoint?.status === 'created' || checkpoint?.status === 'replayed') {
+if (checkpoint?.status === "created" || checkpoint?.status === "replayed") {
   const fork = await environment.workspaceBranching?.fork({
     checkpoint: checkpoint.checkpoint,
-    placement: { kind: 'sandbox', sandboxId: 'analysis-worker' },
-    idempotencyKey: 'analysis-worker',
+    placement: { kind: "sandbox", sandboxId: "analysis-worker" },
+    idempotencyKey: "analysis-worker",
     requestDigest: workspaceForkRequestDigest({
       checkpoint: checkpoint.checkpoint,
-      placement: { kind: 'sandbox', sandboxId: 'analysis-worker' },
+      placement: { kind: "sandbox", sandboxId: "analysis-worker" },
     }),
-  })
+  });
 }
 ```
 
@@ -192,28 +192,35 @@ const provider = createTangleProvider({
   client: new Sandbox({ apiKey: process.env.TANGLE_API_KEY }),
   confidentialAttestationVerifier: async ({ report, attestation }) =>
     (await verifyTangleQuote({ report, attestation })) ?? null,
-})
+});
 ```
 
+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`.
 Every surface carries a freshness discriminator, so a value the Sandbox SDK does not report is visibly absent instead of arriving as a measured zero.
 The `observation` capability flag for a surface is true only when a source can put a value on it for that environment; the observation itself always carries the surface, with `unavailable` and its reason when there is nothing to report.
 
-| Surface | Sandbox source | State when the source is missing |
-| --- | --- | --- |
-| `identity` | provider name and `box.id` | always known |
-| `lifecycle.status` | `box.status` after a refresh | `stale` with the refresh failure |
-| `lifecycle.cleanup` | `box.expiresAt` as a scheduled retirement | omitted from the lifecycle value |
-| `endpoint` | scheme, host, and explicit port of `connection.runtimeUrl` | `unavailable` |
-| `placement.verified` | `client.describePlacement(box)` | `unavailable` |
-| `resources.requested` | the `create()` resource request | omitted on an environment rebuilt by id |
-| `resources.effective` | cgroup `memoryLimitMb` and the attached GPU lease | `unavailable` |
-| `resourceUse.current` / `peak` | cgroup `memoryCurrentMb` / `memoryPeakMb` | `unavailable` |
-| `modelUsage` | the newest execution this handle measured | `unavailable` |
-| `computeBilling` | the GPU lease's billed or estimated customer cost | `unavailable` |
-| `accountUsage` | `client.subscription()` and `client.usage()` | `unavailable` |
+| Surface                        | Sandbox source                                             | State when the source is missing        |
+| ------------------------------ | ---------------------------------------------------------- | --------------------------------------- |
+| `identity`                     | provider name and `box.id`                                 | always known                            |
+| `lifecycle.status`             | `box.status` after a refresh                               | `stale` with the refresh failure        |
+| `lifecycle.cleanup`            | `box.expiresAt` as a scheduled retirement                  | omitted from the lifecycle value        |
+| `endpoint`                     | scheme, host, and explicit port of `connection.runtimeUrl` | `unavailable`                           |
+| `placement.verified`           | `client.describePlacement(box)`                            | `unavailable`                           |
+| `resources.requested`          | the `create()` resource request                            | omitted on an environment rebuilt by id |
+| `resources.effective`          | cgroup `memoryLimitMb` and the attached GPU lease          | `unavailable`                           |
+| `resourceUse.current` / `peak` | cgroup `memoryCurrentMb` / `memoryPeakMb`                  | `unavailable`                           |
+| `modelUsage`                   | the newest execution this handle measured                  | `unavailable`                           |
+| `computeBilling`               | the GPU lease's billed or estimated customer cost          | `unavailable`                           |
+| `accountUsage`                 | `client.subscription()` and `client.usage()`               | `unavailable`                           |
 
 Four quantities have no Sandbox source at all, and the adapter reports them as absent rather than deriving them.
 There is no effective CPU or disk figure anywhere in the SDK, so `resources.effective` carries memory and the accelerator only.
@@ -259,16 +266,16 @@ Set `teamId` inside `exactProcess` to scope create, lookup, and recovery to one
 const provider = createTangleProvider({
   client: new Sandbox({ apiKey: process.env.TANGLE_API_KEY }),
   exactProcess: {},
-})
+});
 
 const environment = await provider.exactProcess!.create({
-  image: 'ghcr.io/acme/agent@sha256:<64-hex-manifest-digest>',
-  egress: { mode: 'blocked' },
+  image: "ghcr.io/acme/agent@sha256:<64-hex-manifest-digest>",
+  egress: { mode: "blocked" },
   maxLifetimeMs: 120_000,
   resources: { cpu: 1, memoryMb: 1024, diskMb: 1024 },
-  metadata: { executionId: 'run-1' },
-  idempotencyKey: 'run-1',
-})
+  metadata: { executionId: "run-1" },
+  idempotencyKey: "run-1",
+});
 ```
 
 The adapter rejects ordinary sandboxes during create, recovery, and list operations.

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-interactive.d.ts

@@ -10,8 +10,8 @@ export interface TangleInteractiveAgentRegistry {
 /**
  * Test the linked SDK surface without accepting any older interactive shape.
  *
- * The current public Sandbox release fails this test. That is intentional:
- * it has no receipt, control claim, or mutation acknowledgement protocol.
+ * Sandbox owns the exact reference, control claim, terminal binding, and
+ * mutation acknowledgements. An older handle shape fails this test closed.
  */
 export declare function sandboxBacksInteractiveAgent(box: SandboxInstanceLike): boolean;
 /**