@terminal3/t3n-sdk 5.2.0 → 5.4.0

package/dist/index.d.ts

@@ -605,6 +605,11 @@ interface QuoteVerifyResult {
     valid: boolean;
     error?: string;
     rtmr3?: string;
+    /**
+     * Base64-encoded RTMR1 (48 bytes). The real rootfs-integrity signal —
+     * see {@link TrustAnchor.rtmr1_allowlist}.
+     */
+    rtmr1?: string;
     report_data?: string;
 }
 interface PeerQuoteResult {
@@ -612,6 +617,8 @@ interface PeerQuoteResult {
     valid: boolean;
     error?: string;
     rtmr3?: string;
+    /** See {@link QuoteVerifyResult.rtmr1}. */
+    rtmr1?: string;
 }
 interface DkgVerifyResult {
     valid: boolean;
@@ -628,7 +635,15 @@ interface DkgVerifyResult {
  * forge a complete, cryptographically-valid bundle for their own key
  * (SP-003). The anchor is the independent ground truth that closes it:
  * the bundle must describe *our* cluster (`expected_peer_ids`) running
- * *our* image (`rtmr3_allowlist`).
+ * *our* image (`rtmr1_allowlist`).
+ *
+ * `rtmr3_allowlist` is checked too, for backward compatibility, but is
+ * **not** the real protection: `tee-init.sh` no longer extends RTMR3
+ * with a content hash, so RTMR3 is a fixed value every
+ * image reports identically. `rtmr1_allowlist` is what actually pins
+ * image identity now — RTMR1 is the TD loader measurement, which under
+ * Trinity's direct-UEFI UKI boot chain captures the UKI PE binary
+ * (embedding the dm-verity root hash in its kernel cmdline).
  */
 interface TrustAnchor {
     /**
@@ -641,9 +656,23 @@ interface TrustAnchor {
      * Base64-encoded 48-byte RTMR3 measurements of the expected node
      * image. Every quote's RTMR3 must be a member. **Must be non-empty.**
      * An array (not a singleton) so a rolling deploy's two in-flight
-     * image measurements both verify.
+     * image measurements both verify. Kept for backward compatibility —
+     * see {@link TrustAnchor} above for why this alone no longer protects
+     * against SP-003.
      */
     rtmr3_allowlist: string[];
+    /**
+     * Base64-encoded 48-byte RTMR1 measurements of the expected node
+     * image. Every quote's RTMR1 must be a member. **Must be non-empty.**
+     * This is the real SP-003 mitigation — see {@link TrustAnchor} above.
+     * Unlike RTMR3's old rolling-deploy-only reason for being an array
+     * (two in-flight image measurements), RTMR1 legitimately needs **more**
+     * entries than that: confirmed empirically, RTMR1 varies by physical
+     * host TDX firmware even for a single, unchanged image, so a fleet's
+     * full firmware diversity — not just old‖new — must all be represented
+     * here.
+     */
+    rtmr1_allowlist: string[];
     /**
      * Optional provenance of the pinned values, for diagnostics only —
      * never passed to the verifier and never part of any security
@@ -684,20 +713,25 @@ declare function isUnsafeTrustServer(anchor: TrustAnchorOrUnsafe): anchor is Uns
  * @param attestationMsgB64 - Base64-encoded attestation message
  *   (for DKG: encaps_key || sorted_peer_id_bytes)
  * @param expectedRtmr3B64 - Optional base64-encoded 48-byte RTMR3
+ * @param expectedRtmr1B64 - Optional base64-encoded 48-byte RTMR1 — the
+ *   real rootfs-integrity signal (see {@link TrustAnchor})
  * @returns Verification result with extracted measurements
  */
-declare function verifyTdxQuote(quoteB64: string, attestationMsgB64: string, expectedRtmr3B64?: string): Promise<QuoteVerifyResult>;
+declare function verifyTdxQuote(quoteB64: string, attestationMsgB64: string, expectedRtmr3B64?: string, expectedRtmr1B64?: string): Promise<QuoteVerifyResult>;
 /**
  * Verify a full DKG attestation bundle against a client-pinned
  * {@link TrustAnchor}: multiple TDX quotes from all participating
  * nodes, plus the binding between the quotes and the ML-KEM
  * encapsulation key. Checks:
- *   1. `expected_peer_ids` / `rtmr3_allowlist` are both non-empty
+ *   1. `expected_peer_ids` / `rtmr3_allowlist` / `rtmr1_allowlist` are
+ *      all non-empty
  *   2. the bundle's `peer_ids` equal the pinned set exactly
  *   3. attestationMsg starts with encapsKey (server can't swap the key)
  *   4. every quote's ECDSA signature chains to Intel's SGX root CA
  *   5. every quote's report_data == keccak512(attestationMsg)
  *   6. every quote's RTMR3 is a member of `rtmr3_allowlist`
+ *   7. every quote's RTMR1 is a member of `rtmr1_allowlist` — the real
+ *      SP-003 mitigation (see {@link TrustAnchor})
  *
  * The anchor is **required**: there is no unauthenticated mode. Callers
  * that genuinely want to trust the server must not call this at all —
@@ -710,7 +744,7 @@ declare function verifyTdxQuote(quoteB64: string, attestationMsgB64: string, exp
  *   (from `/status.dkg_attestation.attestation_msg`)
  * @param peerIds - Base58 peer IDs as reported by the bundle
  * @param quotes - Map of peer_id → base64-encoded TDX quote
- * @param anchor - Client-pinned expected peer IDs + RTMR3 allowlist
+ * @param anchor - Client-pinned expected peer IDs + RTMR allowlists
  * @returns Per-peer verification results and overall validity
  */
 declare function verifyDkgAttestation(encapsKeyB64: string, attestationMsgB64: string, peerIds: string[], quotes: Record<string, string>, anchor: TrustAnchor): Promise<DkgVerifyResult>;
@@ -748,8 +782,9 @@ interface T3nClientConfig {
      * **Required.** Client-pinned trust anchor the node's DKG attestation
      * is verified against before the handshake trusts its ML-KEM key
      * (SP-003). Either a {@link TrustAnchor} (`expected_peer_ids` +
-     * `rtmr3_allowlist`) or the explicit `{ unsafe_trust_server: true }`
-     * opt-out for local dev / mock-signer nodes.
+     * `rtmr1_allowlist` + `rtmr3_allowlist`) or the explicit
+     * `{ unsafe_trust_server: true }` opt-out for local dev / mock-signer
+     * nodes.
      *
      * Without this, a network attacker with their own TDX VM can hand the
      * SDK a forged-but-valid attestation for a key it controls and read
@@ -5221,6 +5256,35 @@ declare class SessionUsageReportClient {
      * org's usage.
      */
     getOrgUsageReport(input: OrgUsageReportInput): Promise<OrgUsageReport>;
+    /**
+     * Fetch how many calls an organisation's members and their agents have
+     * completed so far this calendar year (UTC).
+     *
+     * Counted by CALLER, not by contract owner, so calls into the platform's own
+     * system contracts count as the organisation's usage. Unsuccessful calls and
+     * admin-contract dispatches are excluded, the latter so that reading this
+     * number does not increase it.
+     *
+     * Refuses with `not_org_admin: ...` when the authenticated session DID is
+     * not in the org's admin set, exactly as {@link getOrgUsageReport} does.
+     */
+    getOrgCallCountThisYear(orgDid: string): Promise<number>;
+    /** As {@link getOrgCallCountThisYear}, for a given UTC calendar year. */
+    getOrgCallCountForYear(orgDid: string, year: number): Promise<number>;
+    /**
+     * As {@link getOrgCallCountThisYear}, over an explicit `[fromMs, toMs)`
+     * window in milliseconds.
+     *
+     * Pass whole UTC days (multiples of 86400000) unless you can live with a
+     * figure wider than its label: the counter has day granularity, so the node
+     * widens a ragged window to the days it touches and the count then includes
+     * the hours either side of what was asked for.
+     *
+     * Throws when the window covers more active days than the node reads in one
+     * call — roughly eleven years of unbroken daily use — rather than returning
+     * the partial count the node reports. The year forms cannot reach that.
+     */
+    getOrgCallCountForWindow(orgDid: string, fromMs: number, toMs: number): Promise<number>;
 }
 /**
  * Construct a {@link SessionUsageReportClient} from a caller-owned
@@ -5359,7 +5423,9 @@ interface ConfigValidationResult {
  *
  * The SDK's attestation check (see `TrustAnchor`) needs a trusted source
  * for the expected cluster identity — the set of node peer IDs and the
- * allow-listed RTMR3 image measurements. Without a trusted source, every
+ * allow-listed RTMR1/RTMR3 image measurements (RTMR1 is the real rootfs
+ * signal, RTMR3 is kept for backward compatibility — see `TrustAnchor`'s
+ * own doc comment). Without a trusted source, every
  * caller has to hand-pin those values or fall back to
  * `{ unsafe_trust_server: true }`, which disables verification entirely.
  *
@@ -5375,8 +5441,9 @@ interface ConfigValidationResult {
  * can serve any bytes at the manifest URL, but cannot forge a signature
  * for a manifest naming their own node identities/measurements without
  * the operator's private key. The manifest only ever *narrows* trust to
- * the real cluster — it never widens what the on-quote RTMR3 pinning and
- * peer-id set-equality already enforce inside the WASM verifier.
+ * the real cluster — it never widens what the on-quote RTMR1/RTMR3
+ * pinning and peer-id set-equality already enforce inside the WASM
+ * verifier.
  */
 
 /**
@@ -5391,8 +5458,14 @@ interface SignedTrustManifest {
     version: number;
     /** Base58 peer IDs of the expected cluster nodes. */
     peer_ids: string[];
-    /** Base64-encoded 48-byte RTMR3 measurements of the expected image(s). */
+    /**
+     * Base64-encoded 48-byte RTMR3 measurements of the expected image(s).
+     * Kept for backward compatibility — see `TrustAnchor`'s doc comment
+     * for why `rtmr1_allowlist` is the real rootfs-integrity signal.
+     */
     rtmr3_allowlist: string[];
+    /** Base64-encoded 48-byte RTMR1 measurements of the expected image(s). */
+    rtmr1_allowlist: string[];
     /** RFC 3339 timestamp the manifest was signed. */
     signed_at: string;
     /** Hex secp256k1 signature (compact 64-byte r‖s) over the canonical payload. */