@microsoft/ccf-app 2.0.0-dev4 → 2.0.0-dev8

package/consensus.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @inheritDoc CCFConsensus.getLastCommittedTxId;
+ */
+export declare const getLastCommittedTxId: () => import("./global.js").TransactionId;
+/**
+ * @inheritDoc CCFConsensus.getStatusForTxId;
+ */
+export declare const getStatusForTxId: (view: number, seqno: number) => import("./global.js").TransactionStatus;
+/**
+ * @inheritDoc CCFConsensus.getViewForSeqno;
+ */
+export declare const getViewForSeqno: (seqno: number) => number | null;
+export { TransactionStatus } from "./global";

package/consensus.js

@@ -0,0 +1,21 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the Apache 2.0 License.
+/**
+ * The `consensus` module provides access to consensus information
+ * as observed by the local node.
+ *
+ * @module
+ */
+import { ccf } from "./global.js";
+/**
+ * @inheritDoc CCFConsensus.getLastCommittedTxId;
+ */
+export const getLastCommittedTxId = ccf.consensus.getLastCommittedTxId.bind(ccf.consensus);
+/**
+ * @inheritDoc CCFConsensus.getStatusForTxId;
+ */
+export const getStatusForTxId = ccf.consensus.getStatusForTxId.bind(ccf.consensus);
+/**
+ * @inheritDoc CCFConsensus.getViewForSeqno;
+ */
+export const getViewForSeqno = ccf.consensus.getViewForSeqno.bind(ccf.consensus);

package/converters.js

@@ -97,7 +97,7 @@ class Int32Converter {
 class Uint32Converter {
     encode(val) {
         if (val < 0 || val > 4294967295) {
-            throw new RangeError("value is not within int32 range");
+            throw new RangeError("value is not within uint32 range");
         }
         const buf = new ArrayBuffer(4);
         new DataView(buf).setUint32(0, val, true);

package/crypto.d.ts

@@ -11,7 +11,7 @@ export declare const generateRsaKeyPair: (size: number, exponent?: number | unde
  */
 export declare const wrapKey: (key: ArrayBuffer, wrappingKey: ArrayBuffer, wrapAlgo: import("./global.js").WrapAlgoParams) => ArrayBuffer;
 /**
- * @inheritDoc CCF.crypto.verifySignature
+ * @inheritDoc CCFCrypto.verifySignature
  */
 export declare const verifySignature: (algorithm: import("./global.js").SigningAlgorithm, key: string, signature: ArrayBuffer, data: ArrayBuffer) => boolean;
 /**

package/crypto.js

@@ -27,7 +27,7 @@ export const generateRsaKeyPair = ccf.generateRsaKeyPair;
  */
 export const wrapKey = ccf.wrapKey;
 /**
- * @inheritDoc CCF.crypto.verifySignature
+ * @inheritDoc CCFCrypto.verifySignature
  */
 export const verifySignature = ccf.crypto.verifySignature;
 /**

package/endpoints.d.ts

@@ -46,6 +46,10 @@ export interface Request<T extends JsonCompatible<T> = any> {
      * The query string of the requested URL.
      */
     query: string;
+    /**
+     * The request path of the requested URL.
+     */
+    path: string;
     /**
      * An object to access the request body in various ways.
      */
@@ -192,4 +196,8 @@ export declare type EndpointFn<A extends JsonCompatible<A> = any, B extends Resp
  * @inheritDoc CCF.rpc.setApplyWrites
  */
 export declare const setApplyWrites: (force: boolean) => void;
+/**
+ * @inheritDoc CCF.rpc.setClaimsDigest
+ */
+export declare const setClaimsDigest: (digest: ArrayBuffer) => void;
 export {};

package/endpoints.js

@@ -11,3 +11,7 @@ import { ccf } from "./global.js";
  * @inheritDoc CCF.rpc.setApplyWrites
  */
 export const setApplyWrites = ccf.rpc.setApplyWrites.bind(ccf.rpc);
+/**
+ * @inheritDoc CCF.rpc.setClaimsDigest
+ */
+export const setClaimsDigest = ccf.rpc.setClaimsDigest.bind(ccf.rpc);

package/global.d.ts

@@ -25,6 +25,7 @@ export declare type JsonCompatible<T> = any;
 export interface KvMap {
     has(key: ArrayBuffer): boolean;
     get(key: ArrayBuffer): ArrayBuffer | undefined;
+    getVersionOfPreviousWrite(key: ArrayBuffer): number | undefined;
     set(key: ArrayBuffer, value: ArrayBuffer): KvMap;
     delete(key: ArrayBuffer): boolean;
     clear(): void;
@@ -57,9 +58,9 @@ export interface Receipt {
      */
     signature: string;
     /**
-     * Hex-encoded Merkle tree root hash.
+     * Certificate of the node that signed the Merkle tree root hash.
      */
-    root: string;
+    cert: string;
     /**
      * Merkle tree inclusion proof as an array of ``ProofElement`` objects.
      */
@@ -78,14 +79,25 @@ export interface Receipt {
  */
 export interface HistoricalState {
     /**
-     * The ID of the transaction.
+     * The ID of the transaction, formatted as '<view>.<seqno>' string.
      */
     transactionId: string;
     /**
      * The receipt for the historic transaction.
      */
     receipt: Receipt;
+    /**
+     * An object that provides access to the maps of the Key-Value Store
+     * associated with the historic transaction.
+     * Fields are map names and values are {@linkcode KvMap} objects.
+     */
+    kv: KvMaps;
+}
+export interface TransactionId {
+    view: number;
+    seqno: number;
 }
+export declare type TransactionStatus = "Committed" | "Invalid" | "Pending" | "Unknown";
 /**
  * [RSA-OAEP](https://datatracker.ietf.org/doc/html/rfc8017)
  * key wrapping with SHA-256 as digest function.
@@ -163,6 +175,100 @@ export interface EcdsaParams {
 }
 export declare type SigningAlgorithm = RsaPkcsParams | EcdsaParams;
 export declare type DigestAlgorithm = "SHA-256";
+export interface CCFCrypto {
+    /**
+     * Returns whether digital signature is valid.
+     *
+     * @param algorithm Signing algorithm and parameters
+     * @param key A PEM-encoded public key or X.509 certificate
+     * @param signature Signature to verify
+     * @param data Data that was signed
+     * @throws Will throw an error if the key is not compatible with the
+     *  signing algorithm or if an unknown algorithm is used.
+     */
+    verifySignature(algorithm: SigningAlgorithm, key: string, signature: ArrayBuffer, data: ArrayBuffer): boolean;
+}
+export interface CCFRpc {
+    /**
+     * Set whether KV writes should be applied even if the response status is not 2xx.
+     * The default is `false`.
+     */
+    setApplyWrites(force: boolean): void;
+    /**
+     * Set a claims digest to be associated with the transaction if it succeeds. This
+     * digest can later be accessed from the receipt, and expanded into a full claim.
+     *
+     * The `digest` argument must be a sha-256 ArrayBuffer, eg. produced by {@link CCF.digest}
+     */
+    setClaimsDigest(digest: ArrayBuffer): void;
+}
+export interface CCFConsensus {
+    /**
+     * Get the ID of latest transaction known to be committed.
+     */
+    getLastCommittedTxId(): TransactionId;
+    /**
+     * Get the status of a transaction by ID, provided as a view+seqno pair.
+     *
+     * Note that this value is the node's local understanding of the status
+     * of that transaction in the network at call time. For a given TxID, the
+     * initial status is always UNKNOWN, and eventually becomes COMMITTED or
+     * INVALID. See the documentation section titled "Verifying Transactions"
+     * for more detail.
+     *
+     *         UNKNOWN [Initial status]
+     *          v  ^
+     *        PENDING
+     *        v     v
+     *  COMMITTED INVALID [Final statuses]
+     *
+     * This status is not sampled atomically per handler: if this is called
+     * multiple times in a transaction handler, later calls may see more up to
+     * date values than earlier calls. Once a final state (COMMITTED or INVALID)
+     * has been reached, no further changes are possible.
+     *
+     */
+    getStatusForTxId(view: number, seqno: number): TransactionStatus;
+    /**
+     * Get the view associated with a given seqno, to construct a valid TxID.
+     * If the seqno is not known by the node, `null` is returned.
+     */
+    getViewForSeqno(seqno: number): number | null;
+}
+export interface CCFHistorical {
+    /**
+     * Retrieve a range of historical states containing the state written at the given
+     * indices.
+     *
+     * If this is not currently available, this function returns `null`
+     * and begins fetching the ledger entry asynchronously. This will generally
+     * be true for the first call for a given seqno, and it may take some time
+     * to completely fetch and validate. The call should be repeated later with
+     * the same arguments to retrieve the requested entries. This state is kept
+     * until it is deleted for one of the following reasons:
+     *  - A call to {@linkcode dropCachedStates}
+     *  - `seconds_until_expiry` seconds elapse without calling this function
+     *  - This handle is used to request a different seqno or range
+     *
+     * The range is inclusive of both start_seqno and end_seqno. If a non-empty
+     * array is returned, it will always contain the full requested range; the
+     * array will be of length (end_seqno - start_seqno + 1).
+     *
+     * If the requested range failed to be retrieved then `null` is returned.
+     * This may happen if the range is not known to the node (see also
+     * {@linkcode CCFConsensus.getStatusForTxId | getStatusForTxId}) or not available for
+     * other reasons (for example, the node is missing ledger files on disk).
+     */
+    getStateRange(handle: number, startSeqno: number, endSeqno: number, secondsUntilExpiry: number): HistoricalState[] | null;
+    /** Drop cached states for the given handle.
+     *
+     * May be used to free up space once a historical query has been resolved,
+     * more aggressively than waiting for the requests to expire.
+     *
+     * Returns `true` if the handle was found and dropped, `false` otherwise.
+     */
+    dropCachedStates(handle: number): boolean;
+}
 export interface CCF {
     /**
      * Convert a string into an ArrayBuffer.
@@ -221,26 +327,9 @@ export interface CCF {
      * The chain and trusted certificates are PEM-encoded bundles of X.509 certificates.
      */
     isValidX509CertChain(chain: string, trusted: string): boolean;
-    crypto: {
-        /**
-         * Returns whether digital signature is valid.
-         *
-         * @param algorithm Signing algorithm and parameters
-         * @param key A PEM-encoded public key or X.509 certificate
-         * @param signature Signature to verify
-         * @param data Data that was signed
-         * @throws Will throw an error if the key is not compatible with the
-         *  signing algorithm or if an unknown algorithm is used.
-         */
-        verifySignature(algorithm: SigningAlgorithm, key: string, signature: ArrayBuffer, data: ArrayBuffer): boolean;
-    };
-    rpc: {
-        /**
-         * Set whether KV writes should be applied even if the response status is not 2xx.
-         * The default is `false`.
-         */
-        setApplyWrites(force: boolean): void;
-    };
+    crypto: CCFCrypto;
+    rpc: CCFRpc;
+    consensus: CCFConsensus;
     /**
      * An object that provides access to the maps of the Key-Value Store of CCF.
      * Fields are map names and values are {@linkcode KvMap} objects.
@@ -251,6 +340,7 @@ export interface CCF {
      * Only defined for endpoints with "mode" set to "historical".
      */
     historicalState?: HistoricalState;
+    historical: CCFHistorical;
 }
 export declare const openenclave: OpenEnclave;
 export interface EvidenceClaims {

package/historical.d.ts

@@ -2,4 +2,12 @@
  * @inheritDoc CCF.historicalState
  */
 export declare const historicalState: import("./global.js").HistoricalState | undefined;
+/**
+ * @inheritDoc CCFHistorical.getStateRange
+ */
+export declare const getStateRange: (handle: number, startSeqno: number, endSeqno: number, secondsUntilExpiry: number) => import("./global.js").HistoricalState[] | null;
+/**
+ * @inheritDoc CCFHistorical.dropCachedStates
+ */
+export declare const dropCachedStates: (handle: number) => boolean;
 export { HistoricalState, Receipt, Proof, ProofElement } from "./global";

package/historical.js

@@ -1,11 +1,29 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the Apache 2.0 License.
 /**
- * This module provides access to the historical state
- * in historic endpoints, corresponding to a specific transaction.
+ * This module provides access to historical state.
  *
- * Note that the Key-Value Store also reflects the historic state
- * and can be accessed through the {@linkcode kv} module as usual.
+ * There are two options to access historical state:
+ *
+ * 1. Declare the endpoint mode as `"historical"` in `app.json`
+ * and access historical state via `ccf.historicalState`.
+ *
+ * This option supports single transactions only and prescribes
+ * how the transaction ID must be passed in the request (via
+ * the `x-ms-ccf-transaction-id` HTTP header).
+ * The {@linkcode historicalState} property provides access to
+ * the historical state of the Key-Value store and information
+ * like the transaction receipt.
+ *
+ * 2. Declare the endpoint mode as `"readonly"` in `app.json` and use
+ * the programmatic API to request historical state.
+ *
+ * This option supports both single and multi-transaction requests.
+ * It also leaves the decision of how to extract the transaction ID(s)
+ * from the HTTP request to the app developer.
+ * The {@linkcode getStateRange} function of this module
+ * provides access to a sequential range of transactions.
+ * See the documentation of that function for more details.
  *
  * @module
  */
@@ -14,3 +32,11 @@ import { ccf } from "./global.js";
  * @inheritDoc CCF.historicalState
  */
 export const historicalState = ccf.historicalState;
+/**
+ * @inheritDoc CCFHistorical.getStateRange
+ */
+export const getStateRange = ccf.historical.getStateRange.bind(ccf.historical);
+/**
+ * @inheritDoc CCFHistorical.dropCachedStates
+ */
+export const dropCachedStates = ccf.historical.dropCachedStates.bind(ccf.historical);

package/index.d.ts

@@ -13,5 +13,6 @@
  */
 export * from "./kv.js";
 export * from "./converters.js";
+export * from "./consensus.js";
 export * from "./historical.js";
 export * from "./endpoints.js";

package/index.js

@@ -15,5 +15,6 @@
  */
 export * from "./kv.js";
 export * from "./converters.js";
+export * from "./consensus.js";
 export * from "./historical.js";
 export * from "./endpoints.js";

package/kv.d.ts

@@ -20,6 +20,17 @@
  * foo.set("key-1", {"prop1": 42});
  * ```
  *
+ * Example of using typed access with historical state:
+ * ```
+ * import * as ccfapp from '@microsoft/ccf-app';
+ *
+ * const states = ccfapp.getStateRange(handle, begin, end, expiry);
+ * // ... error handling ...
+ * const firstKv = states[0].kv;
+ * const foo = ccfapp.typedKv(firstKv['foo'], ccfapp.string, ccfapp.json);
+ * const val = foo.get("key-1");
+ * ```
+ *
  * @module
  */
 import { KvMap } from "./global.js";
@@ -45,11 +56,12 @@ export declare class TypedKvMap<K, V> {
  *
  * See the {@linkcode converters} module for available converters.
  *
- * @param name The map name in the Key-Value Store.
+ * @param nameOrMap Either the map name in the Key-Value Store,
+ *    or a ``KvMap`` object.
  * @param kt The converter to use for map keys.
  * @param vt The converter to use for map values.
  */
-export declare function typedKv<K, V>(name: string, kt: DataConverter<K>, vt: DataConverter<V>): TypedKvMap<K, V>;
+export declare function typedKv<K, V>(nameOrMap: string | KvMap, kt: DataConverter<K>, vt: DataConverter<V>): TypedKvMap<K, V>;
 /**
  * @inheritDoc CCF.kv
  */

package/kv.js

@@ -22,6 +22,17 @@
  * foo.set("key-1", {"prop1": 42});
  * ```
  *
+ * Example of using typed access with historical state:
+ * ```
+ * import * as ccfapp from '@microsoft/ccf-app';
+ *
+ * const states = ccfapp.getStateRange(handle, begin, end, expiry);
+ * // ... error handling ...
+ * const firstKv = states[0].kv;
+ * const foo = ccfapp.typedKv(firstKv['foo'], ccfapp.string, ccfapp.json);
+ * const val = foo.get("key-1");
+ * ```
+ *
  * @module
  */
 import { ccf } from "./global.js";
@@ -68,12 +79,14 @@ export class TypedKvMap {
  *
  * See the {@linkcode converters} module for available converters.
  *
- * @param name The map name in the Key-Value Store.
+ * @param nameOrMap Either the map name in the Key-Value Store,
+ *    or a ``KvMap`` object.
  * @param kt The converter to use for map keys.
  * @param vt The converter to use for map values.
  */
-export function typedKv(name, kt, vt) {
-    return new TypedKvMap(ccf.kv[name], kt, vt);
+export function typedKv(nameOrMap, kt, vt) {
+    const kvMap = typeof nameOrMap === "string" ? ccf.kv[nameOrMap] : nameOrMap;
+    return new TypedKvMap(kvMap, kt, vt);
 }
 /**
  * @inheritDoc CCF.kv

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/ccf-app",
-  "version": "2.0.0-dev4",
+  "version": "2.0.0-dev8",
   "description": "CCF app support package",
   "main": "index.js",
   "files": [
@@ -13,23 +13,22 @@
     "build": "tsc",
     "test": "cross-env TS_NODE_PROJECT=test/tsconfig.json mocha --loader=ts-node/esm test/**/*.test.ts",
     "docs": "typedoc",
-    "docs:serve": "rm -rf html && concurrently \"typedoc --watch --preserveWatchOutput\" \"serve html\""
+    "docs:watch": "rm -rf html && typedoc --watch --preserveWatchOutput"
   },
   "author": "Microsoft",
   "license": "Apache-2.0",
   "devDependencies": {
     "@types/chai": "^4.2.15",
-    "@types/mocha": "^8.2.2",
-    "@types/node": "^14.14.35",
-    "@types/node-forge": "^0.9.7",
+    "@types/mocha": "^9.0.0",
+    "@types/node": "^17.0.8",
+    "@types/node-forge": "^1.0.0",
     "chai": "^4.3.4",
-    "concurrently": "^6.0.0",
+    "colors": "1.4.0",
     "cross-env": "^7.0.3",
-    "mocha": "^8.3.2",
-    "node-forge": "^0.10.0",
-    "serve": "^11.3.2",
-    "ts-node": "^9.1.1",
-    "typedoc": "^0.20.34",
-    "typescript": "4.2.4"
+    "mocha": "^9.1.3",
+    "node-forge": "^1.2.0",
+    "ts-node": "^10.4.0",
+    "typedoc": "^0.22.7",
+    "typescript": "^4.2.4"
   }
 }

package/polyfill.js

@@ -29,6 +29,9 @@ class KvMapPolyfill {
     get(key) {
         return this.map.get(base64(key));
     }
+    getVersionOfPreviousWrite(key) {
+        throw new Error("Not implemented");
+    }
     set(key, value) {
         this.map.set(base64(key), value);
         return this;
@@ -60,10 +63,32 @@ class CCFPolyfill {
                 return Reflect.get(target, name, receiver);
             },
         });
+        this.consensus = {
+            getLastCommittedTxId() {
+                throw new Error("Not implemented");
+            },
+            getStatusForTxId(view, seqno) {
+                throw new Error("Not implemented");
+            },
+            getViewForSeqno(seqno) {
+                throw new Error("Not implemented");
+            },
+        };
+        this.historical = {
+            getStateRange(handle, startSeqno, endSeqno, secondsUntilExpiry) {
+                throw new Error("Not implemented");
+            },
+            dropCachedStates(handle) {
+                throw new Error("Not implemented");
+            },
+        };
         this.rpc = {
             setApplyWrites(force) {
                 throw new Error("Not implemented");
             },
+            setClaimsDigest(digest) {
+                throw new Error("Not implemented");
+            },
         };
         this.crypto = {
             verifySignature(algorithm, key, signature, data) {