@ixo/action-protocol 0.0.0-stage → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,46 @@
1
+ # Changelog
2
+
3
+ ## 0.5.0
4
+
5
+ Everything in the P1 0.3.0 entry below (shipped on the stacked P1 branch), on
6
+ top of 0.4.1, plus:
7
+
8
+ - Operation JSON schema: bank `denom` is any Cosmos denom (`DENOM`, optional,
9
+ default `uixo`) and `feeBaseUnits` is optional (the Hub simulates the fee).
10
+ Optional schema properties are validated when present.
11
+ - `/options?version=3` (`ixo.auth-options/3`): V2 plus `transfer.tokens`
12
+ (`OptionsToken`: `denom`, `symbol`, `decimals`, `verified`,
13
+ `balanceBaseUnits`), parsed by `parseOptionsTransfer`. V1/V2 unchanged.
14
+ - Wire changes summary for consumers:
15
+ - outcome callbacks are signed (`x-auth-hub-timestamp`, `x-auth-hub-key-id`,
16
+ `x-auth-hub-signature` over `${timestamp}.${audience}.${sha256hex(body)}`);
17
+ the per-account `x-auth-hub-outcome-key` header is gone;
18
+ - v2 bank receipts add `denom` + `amountBaseUnits`; v1 receipts are the
19
+ 0.4.1 shape exactly;
20
+ - review views may carry `transfer` (`TransferDisplay` with `verified`);
21
+ - v2 capabilities `transfer` is `{limits, maxFeeUixo}`; v1 keeps
22
+ `{maxAmountUixo, maxFeeUixo}`.
23
+
24
+ ## 0.3.0
25
+
26
+ All additions are optional or v2-only; v1 envelopes are unchanged.
27
+
28
+ - Bank send `denom`: any Cosmos denom matching `DENOM`; absent means `uixo`
29
+ (the parser fills it in).
30
+ - Bank send `feeBaseUnits`: optional; the Hub ignores it and simulates the fee.
31
+ - Bank receipt: optional `denom` and `amountBaseUnits`. `parseOutcome` rejects
32
+ them (and `reason`) in an `ixo.auth-outcome/1` envelope; `outcomeForVersion`
33
+ and the new `v1Receipt` strip them for v1 callers.
34
+ - Review view: optional `transfer` (`TransferDisplay`, parsed by
35
+ `parseTransferDisplay`): Hub-computed amount display, symbol, decimals,
36
+ `verified` (false = untrusted metadata: base units, show the full denom and
37
+ an unverified marker), simulated fee, gas limit and fee granter.
38
+ - Capabilities `transfer`: new `{limits: [{denom, maxAmountBaseUnits}],
39
+ maxFeeUixo?}` form beside the legacy `{maxAmountUixo, maxFeeUixo}`.
40
+ - Signed outcome callbacks: `OUTCOME_SIGNATURE_HEADERS`,
41
+ `OUTCOME_SIGNATURE_MAX_SKEW_SECONDS` (300), `outcomeAudience`,
42
+ `outcomeSigningPayload`, `signOutcomeRequest`, `verifyOutcomeRequest`,
43
+ `ed25519PublicKeyFromMultibase`, `publicKeyFromDidDocument`. The signed
44
+ string is `${timestamp}.${audience}.${sha256hex(rawBody)}` with audience =
45
+ the receiving oracle's https origin; `verifyOutcomeRequest` requires
46
+ `expectedAudience`. Receivers dedupe by event id.
package/README.md CHANGED
@@ -1,3 +1,100 @@
1
- # Temporary Holding Version
1
+ # @ixo/action-protocol
2
2
 
3
- 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.
3
+ Dependency-free wire parsers, types and helpers for Auth Hub action operations
4
+ (`ixo-auth-hub` `/api/internal/actions/*` and the outcome callbacks). The Hub,
5
+ the channel gateway and oracle runtimes use the same parsers, so a shape one
6
+ side emits is exactly what the other side accepts.
7
+
8
+ The full API is documented in `docs/action-operations-api.md` in the
9
+ ixo-auth-hub repository. This file covers the contract a consumer must follow.
10
+
11
+ ## Envelope versions
12
+
13
+ Callers declare the envelope version they parse with `?version=2` on
14
+ `GET /capabilities`, `POST /operations` and `GET /operations/:id`.
15
+
16
+ - v1 (`ixo.auth-outcome/1`, `ixo.auth-capabilities/1`): the 0.1.0 status set
17
+ and the 0.4.1 receipt shape, exactly. Fields added later never appear in v1.
18
+ - v2 (`ixo.auth-outcome/2`, `ixo.auth-capabilities/2`): every current field.
19
+
20
+ ## Bank send (`ixo.bank.send.v1`)
21
+
22
+ - `denom`: any Cosmos denom matching `DENOM`
23
+ (`^[a-zA-Z][a-zA-Z0-9/:._-]{2,127}$`); absent means `uixo`.
24
+ - `feeBaseUnits`: optional and ignored. The Hub simulates gas and fee itself
25
+ and freezes them into the SignDoc.
26
+ - The review view carries `transfer` (`TransferDisplay`): the Hub-computed
27
+ `amountDisplay`, `symbol`, `decimals`, `verified`, `feeBaseUnits`,
28
+ `feeDenom` (`uixo`), `feeDisplay`, `gasLimit` and `feeGranter`. Never do
29
+ decimal math or guess `ibc/` hashes on the client; show what the Hub returns.
30
+ - `verified` is true only for `uixo` and `ibc/` denoms with metadata. When it
31
+ is false the symbol and decimals are not trusted (anyone controlling a
32
+ factory/cw20 token can call it "USDC"): `decimals` is 0, `amountDisplay` is
33
+ base units, and the UI must show the full denom and an "unverified token"
34
+ marker. Show the full denom for anything that is not `uixo`.
35
+ - v2 bank receipts carry `denom` and `amountBaseUnits`.
36
+
37
+ ## Options
38
+
39
+ `GET /options?version=3` (`ixo.auth-options/3`) is V2 plus
40
+ `transfer: {tokens: [{denom, symbol, decimals, verified, balanceBaseUnits}]} | null`
41
+ (one AllBalances page, at most 50 tokens). The same `verified` rule as the
42
+ review view applies. Copy `denom` and base-unit amounts from it; V2 is
43
+ unchanged, so 0.4.1 parsers keep working on V2.
44
+
45
+ ## Capabilities
46
+
47
+ `transfer` is either `{limits: [{denom, maxAmountBaseUnits}], maxFeeUixo?}`
48
+ (v2; an empty `limits` means no caps) or the legacy
49
+ `{maxAmountUixo, maxFeeUixo}` (v1).
50
+
51
+ ## Signed outcome callbacks
52
+
53
+ The Hub signs every callback with its service DID key, the `#key-0` Ed25519
54
+ key in `https://<hub host>/.well-known/did.json`.
55
+
56
+ | Header | Value |
57
+ | --- | --- |
58
+ | `x-auth-hub-timestamp` | unix seconds |
59
+ | `x-auth-hub-key-id` | `did:web:<hub host>#key-0` |
60
+ | `x-auth-hub-signature` | base64url Ed25519 over `${timestamp}.${audience}.${sha256hex(rawBody)}` |
61
+
62
+ `audience` is your https origin (the origin of the oracle URL registered on
63
+ the channel account). It is not sent: pass your own public origin from
64
+ configuration as the required `expectedAudience`, so a callback signed for
65
+ another oracle never verifies at yours. Verify with the exact raw body bytes,
66
+ the Hub DID you were configured with (never a DID taken from the request) and
67
+ a 300 s maximum clock skew, and dedupe accepted callbacks by event id (a
68
+ valid callback can arrive again within the skew window or on a Hub retry):
69
+
70
+ ```js
71
+ import {
72
+ parseOutcome,
73
+ publicKeyFromDidDocument,
74
+ verifyOutcomeRequest,
75
+ } from "@ixo/action-protocol";
76
+
77
+ const hubDid = "did:web:auth.ixo.earth"; // configuration, not the request
78
+ const keyId = `${hubDid}#key-0`;
79
+ const didDocument = await (
80
+ await fetch("https://auth.ixo.earth/.well-known/did.json")
81
+ ).json(); // cache this
82
+ const rawBody = await request.text();
83
+ const ok = await verifyOutcomeRequest({
84
+ rawBody,
85
+ headers: request.headers,
86
+ publicKey: publicKeyFromDidDocument(didDocument, keyId),
87
+ expectedKeyId: keyId,
88
+ expectedAudience: "https://oracle.example", // your own origin, from config
89
+ });
90
+ if (!ok) return new Response("unauthorized", { status: 401 });
91
+ const outcome = parseOutcome(JSON.parse(rawBody));
92
+ ```
93
+
94
+ Uses WebCrypto Ed25519 only (Node 20+, Cloudflare Workers, modern browsers).
95
+
96
+ ## Tests
97
+
98
+ ```sh
99
+ node --test test/*.test.mjs
100
+ ```
package/package.json CHANGED
@@ -1,6 +1,32 @@
1
1
  {
2
2
  "name": "@ixo/action-protocol",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.5.0",
4
+ "description": "Shared wire contract between IXO Auth Hub, oracle runtimes and channel gateways for reviewed action cards (operations, capabilities, outcomes, receipts).",
5
+ "license": "Apache-2.0",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/ixoworld/ixo-auth-hub.git",
9
+ "directory": "packages/action-protocol"
10
+ },
11
+ "homepage": "https://github.com/ixoworld/ixo-auth-hub/tree/main/packages/action-protocol",
12
+ "type": "module",
13
+ "exports": {
14
+ ".": {
15
+ "types": "./src/index.d.ts",
16
+ "default": "./src/index.js"
17
+ }
18
+ },
19
+ "files": [
20
+ "src",
21
+ "CHANGELOG.md"
22
+ ],
23
+ "engines": {
24
+ "node": ">=20"
25
+ },
26
+ "publishConfig": {
27
+ "access": "public"
28
+ },
29
+ "scripts": {
30
+ "test": "node --test test/*.test.mjs"
31
+ }
32
+ }