@1shotapi/ows-clear-signing 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# @1shotapi/ows-clear-signing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ERC-7730 clear signing for OWS Branding Layers.
+
+The 1Shot Relayer keeps a synced copy of the
+[ERC-7730 registry](https://github.com/ethereum/clear-signing-erc7730-registry) and serves one
+**resolved** descriptor per request (`includes` merged, definitions inlined, trimmed to the matching
+format). This package does everything wallet-side:
+
+- `ClearSigningUtils.calldataLookupKey(chainId, to, data)`: `{ chainId, address, selector }` for `GET /clear-signing/calldata`
+- `ClearSigningUtils.eip712LookupKey(typedData)`: `{ chainId, verifyingContract, primaryType, encodeTypeHash }` for `GET /clear-signing/eip712`
+- `ClearSigningFormatter`: renders a resolved descriptor into an `IClearSigningDisplay` (intent, interpolated intent, labeled fields)
+
+Validate Relayer responses with `ClearSigningLookupResultSchema` from `@1shotapi/ows-types`.
+
+## Trust model
+
+The formatter re-verifies everything it can locally, so a compromised resolver can only change
+labels. It can never change the decoded values shown to the user.
+
+- **Calldata:** `context.contract.deployments` must contain `(chainId, to)`. The selector of `format.key` must equal `data[0:4]`. Arguments are decoded by the wallet from `format.key`.
+- **EIP-712:** the domain must have `chainId` and `verifyingContract`. The `context.eip712` deployments, domain and `domainSeparator` constraints must hold. `format.key` must equal `encodeType(primaryType)`.
+
+Any failure throws `ClearSigningError`. Callers MUST then fall back to their generic signing UI.
+
+## Usage
+
+```ts
+import { ClearSigningFormatter, ClearSigningUtils } from "@1shotapi/ows-clear-signing";
+import { ClearSigningLookupResultSchema } from "@1shotapi/ows-types";
+
+const key = ClearSigningUtils.calldataLookupKey(chainId, to, data);
+const result = ClearSigningLookupResultSchema.parse(await (await fetch(url)).json());
+if (result.found) {
+  const formatter = new ClearSigningFormatter(environment); // IClearSigningEnvironment
+  const display = await formatter.formatCalldata(result.descriptor, { chainId, from, to, data, value });
+}
+```
+
+`IClearSigningEnvironment` supplies the following, each returning `null` when unknown:
+
+- token metadata
+- the native currency
+- chain names
+- address names
+
+The formatter does no network I/O of its own.
+
+## Supported formats
+
+- Fully supported: `raw`, `amount`, `tokenAmount` (threshold/message, `nativeCurrencyAddress`, `chainId`), `addressName` ("You" for the signer, `senderAddress`), `tokenTicker`, `nftName`, `date` (timestamp, blockheight), `duration`, `unit` (with SI prefixes), `enum`, `chainId`.
+- `calldata`: rendered as "Embedded call to …" without recursive decoding.
+- `interoperableAddressName`: rendered raw.
+
+Paths support the `#.`, `@.` and `$.` roots, as well as relative paths, indices, negative indices, byte and array slices, `[]` iteration, groups (`sequential` / `bundled`), array-indexed params, `metadata.maps` references, and `visible` rules (`never` / `optional` / `ifNotIn` / `mustMatch`).

package/dist/ClearSigningError.d.ts

@@ -0,0 +1,10 @@
+import { OwsError } from "@1shotapi/ows-types";
+/**
+ * A descriptor cannot be applied to this transaction / message: binding mismatch, selector
+ * or type-hash mismatch, unresolvable path, invalid map reference, failed `mustMatch`, etc.
+ * Callers MUST fall back to their generic (non clear-signed) display.
+ */
+export declare class ClearSigningError extends OwsError {
+    constructor(message: string);
+}
+//# sourceMappingURL=ClearSigningError.d.ts.map

package/dist/ClearSigningError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClearSigningError.d.ts","sourceRoot":"","sources":["../src/ClearSigningError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,EAAE,MAAM;CAI5B"}

package/dist/ClearSigningError.js

@@ -0,0 +1,13 @@
+import { OwsError } from "@1shotapi/ows-types";
+/**
+ * A descriptor cannot be applied to this transaction / message: binding mismatch, selector
+ * or type-hash mismatch, unresolvable path, invalid map reference, failed `mustMatch`, etc.
+ * Callers MUST fall back to their generic (non clear-signed) display.
+ */
+export class ClearSigningError extends OwsError {
+    constructor(message) {
+        super(message);
+        this.name = "ClearSigningError";
+    }
+}
+//# sourceMappingURL=ClearSigningError.js.map

package/dist/ClearSigningError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClearSigningError.js","sourceRoot":"","sources":["../src/ClearSigningError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,QAAQ;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF"}

package/dist/ClearSigningFormatter.d.ts

@@ -0,0 +1,26 @@
+import { EVMAccountAddress, type IClearSigningDescriptor } from "@1shotapi/ows-types";
+import { type IClearSigningDisplay, type IClearSigningEnvironment, type IClearSigningTransaction, type IClearSigningTypedData } from "./interfaces.js";
+/**
+ * Renders an ERC-7730 descriptor (as resolved by the Relayer) against a transaction or EIP-712
+ * message. Every binding the wallet can check locally is re-verified here, so a compromised
+ * resolver can at worst mislabel fields — never change decoded values:
+ *
+ * - calldata: `context.contract.deployments` contains (chainId, to); the format key's selector
+ *   equals `data[0:4]`; arguments are decoded by the wallet from the format key.
+ * - EIP-712: `context.eip712` deployments / domain / domainSeparator constraints hold; the
+ *   format key equals `encodeType(primaryType)` of the message being signed.
+ *
+ * Throws {@link ClearSigningError} when the descriptor cannot be applied; callers fall back to
+ * their generic display.
+ */
+export declare class ClearSigningFormatter {
+    private readonly environment;
+    constructor(environment: IClearSigningEnvironment);
+    formatCalldata(descriptor: IClearSigningDescriptor, transaction: IClearSigningTransaction): Promise<IClearSigningDisplay>;
+    formatTypedData(descriptor: IClearSigningDescriptor, typedData: IClearSigningTypedData, signer: EVMAccountAddress): Promise<IClearSigningDisplay>;
+    private verifyEip712Binding;
+    private domainValueEquals;
+    private matchesDeployment;
+    private container;
+}
+//# sourceMappingURL=ClearSigningFormatter.d.ts.map

package/dist/ClearSigningFormatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClearSigningFormatter.d.ts","sourceRoot":"","sources":["../src/ClearSigningFormatter.ts"],"names":[],"mappings":"AAOA,OAAO,EAML,iBAAiB,EAKjB,KAAK,uBAAuB,EAE7B,MAAM,qBAAqB,CAAC;AAU7B,OAAO,EAEL,KAAK,oBAAoB,EAEzB,KAAK,wBAAwB,EAE7B,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC5B,MAAM,iBAAiB,CAAC;AAYzB;;;;;;;;;;;;GAYG;AACH,qBAAa,qBAAqB;IACpB,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,wBAAwB;IAE5D,cAAc,CAClB,UAAU,EAAE,uBAAuB,EACnC,WAAW,EAAE,wBAAwB,GACpC,OAAO,CAAC,oBAAoB,CAAC;IA+B1B,eAAe,CACnB,UAAU,EAAE,uBAAuB,EACnC,SAAS,EAAE,sBAAsB,EACjC,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,oBAAoB,CAAC;IAsBhC,OAAO,CAAC,mBAAmB;IAyC3B,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,SAAS;CAalB"}