@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 +46 -0
- package/README.md +99 -2
- package/package.json +30 -4
- package/src/index.d.ts +559 -0
- package/src/index.js +1335 -0
- package/src/operation-schema.js +181 -0
- package/src/outcome-signature.js +217 -0
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
|
-
#
|
|
1
|
+
# @ixo/action-protocol
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|