@lunora/x402 0.0.0 → 1.0.0-alpha.2

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.
Files changed (25) hide show
  1. package/LICENSE.md +111 -0
  2. package/README.md +43 -28
  3. package/__assets__/package-og.svg +14 -0
  4. package/dist/charge/index.d.mts +76 -0
  5. package/dist/charge/index.d.ts +76 -0
  6. package/dist/charge/index.mjs +7 -0
  7. package/dist/index.d.mts +6 -0
  8. package/dist/index.d.ts +6 -0
  9. package/dist/index.mjs +2 -0
  10. package/dist/packem_shared/DEFAULT_FACILITATOR_URL-Cbz6kIqa.mjs +4 -0
  11. package/dist/packem_shared/DEFAULT_STABLECOIN_DECIMALS-CSu5b5lD.mjs +85 -0
  12. package/dist/packem_shared/EVM_NETWORKS-BhnYWUQ4.mjs +26 -0
  13. package/dist/packem_shared/config.d-CddwCiBm.d.mts +325 -0
  14. package/dist/packem_shared/config.d-CddwCiBm.d.ts +325 -0
  15. package/dist/packem_shared/createChargeMiddleware-BJkYJeFf.mjs +148 -0
  16. package/dist/packem_shared/createFacilitatorClient-rXHBnCZm.mjs +16 -0
  17. package/dist/packem_shared/createPayFetch-O2vkvM1v.mjs +17 -0
  18. package/dist/packem_shared/createProcedureChargeGate-CV8ITlQP.mjs +19 -0
  19. package/dist/packem_shared/registerWallet-I4pVwq65.mjs +109 -0
  20. package/dist/packem_shared/toPaymentEventRow-DW4O9N7Y.mjs +22 -0
  21. package/dist/packem_shared/withX402-rUq0voT8.mjs +15 -0
  22. package/dist/pay/index.d.mts +77 -0
  23. package/dist/pay/index.d.ts +77 -0
  24. package/dist/pay/index.mjs +21 -0
  25. package/package.json +75 -7
package/LICENSE.md ADDED
@@ -0,0 +1,111 @@
1
+ # Functional Source License, Version 1.1, Apache 2.0 Future License
2
+
3
+ ## Abbreviation
4
+
5
+ FSL-1.1-Apache-2.0
6
+
7
+ ## Notice
8
+
9
+ Copyright 2026 anolilab and contributors
10
+
11
+ ## Terms and Conditions
12
+
13
+ ### Licensor ("We")
14
+
15
+ The party offering the Software under these Terms and Conditions.
16
+
17
+ ### The Software
18
+
19
+ The "Software" is each version of the software that we make available under
20
+ these Terms and Conditions, as indicated by our inclusion of these Terms and
21
+ Conditions with the Software.
22
+
23
+ ### License Grant
24
+
25
+ Subject to your compliance with this License Grant and the Patents,
26
+ Redistribution and Trademark clauses below, we hereby grant you the right to
27
+ use, copy, modify, create derivative works, publicly perform, publicly display
28
+ and redistribute the Software for any Permitted Purpose identified below.
29
+
30
+ ### Permitted Purpose
31
+
32
+ A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
33
+ means making the Software available to others in a commercial product or service
34
+ that:
35
+
36
+ 1. substitutes for the Software;
37
+
38
+ 2. substitutes for any other product or service we offer using the Software that
39
+ exists as of the date we make the Software available; or
40
+
41
+ 3. offers the same or substantially similar functionality as the Software.
42
+
43
+ Permitted Purposes specifically include using the Software:
44
+
45
+ 1. for your internal use and access;
46
+
47
+ 2. for non-commercial education;
48
+
49
+ 3. for non-commercial research; and
50
+
51
+ 4. in connection with professional services that you provide to a licensee using
52
+ the Software in accordance with these Terms and Conditions.
53
+
54
+ ### Patents
55
+
56
+ To the extent your use for a Permitted Purpose would necessarily infringe our
57
+ patents, the license grant above includes a license under our patents. If you
58
+ make a claim against any party that the Software infringes or contributes to the
59
+ infringement of any patent, then your patent license to the Software ends
60
+ immediately.
61
+
62
+ ### Redistribution
63
+
64
+ The Terms and Conditions apply to all copies, modifications and derivatives of
65
+ the Software.
66
+
67
+ If you redistribute any copies, modifications or derivatives of the Software,
68
+ you must include a copy of or a link to these Terms and Conditions and not
69
+ remove any copyright notices provided in or with the Software.
70
+
71
+ ### Disclaimer
72
+
73
+ THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
74
+ IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
75
+ PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
76
+
77
+ IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
78
+ SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN
79
+ IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
80
+
81
+ ### Trademarks
82
+
83
+ Except for displaying the License Details and identifying us as the origin of
84
+ the Software, you have no right under these Terms and Conditions to use our
85
+ trademarks, trade names, service marks or product names.
86
+
87
+ ## Grant of Future License
88
+
89
+ We hereby irrevocably grant you an additional license to use the Software under
90
+ the Apache License, Version 2.0 that is effective on the second anniversary of
91
+ the date we make the Software available. On or after that date, you may use the
92
+ Software under the Apache License, Version 2.0, in which case the following will
93
+ apply:
94
+
95
+ Licensed under the Apache License, Version 2.0 (the "License"); you may not use
96
+ this file except in compliance with the License.
97
+
98
+ You may obtain a copy of the License at
99
+
100
+ http://www.apache.org/licenses/LICENSE-2.0
101
+
102
+ Unless required by applicable law or agreed to in writing, software distributed
103
+ under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
104
+ CONDITIONS OF ANY KIND, either express or implied. See the License for the
105
+ specific language governing permissions and limitations under the License.
106
+
107
+ <!-- DEPENDENCIES -->
108
+ <!-- /DEPENDENCIES -->
109
+
110
+ <!-- TYPE_DEPENDENCIES -->
111
+ <!-- /TYPE_DEPENDENCIES -->
package/README.md CHANGED
@@ -1,45 +1,60 @@
1
1
  # @lunora/x402
2
2
 
3
- ## ⚠️ IMPORTANT NOTICE ⚠️
3
+ > Agentic payments over the [x402](https://x402.org) protocol for [Lunora](https://lunora.sh).
4
4
 
5
- **This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
5
+ x402 turns HTTP `402 Payment Required` into a machine-payable rail: no accounts,
6
+ no API keys, no webhooks — an agent pays per request in stablecoin (USDC) and a
7
+ third-party **facilitator** verifies and settles the payment on-chain.
6
8
 
7
- This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
9
+ `@lunora/x402` gives a Lunora app both sides of that exchange, as two
10
+ independently tree-shakeable subpaths:
8
11
 
9
- ## Purpose
12
+ | Subpath | Rail | Who uses it |
13
+ | --------------------- | ---------- | -------------------------------------------------------------------------------------------------- |
14
+ | `@lunora/x402/charge` | **charge** | Your deployment **sells** — gate an HTTP-action route, a procedure, or an MCP tool behind a price. |
15
+ | `@lunora/x402/pay` | **pay** | Your action/agent **buys** — pay an x402-gated resource on the way out. |
10
16
 
11
- This package exists to:
12
- 1. Configure OIDC trusted publishing for the package name `@lunora/x402`
13
- 2. Enable secure, token-less publishing from CI/CD workflows
14
- 3. Establish provenance for packages published under this name
17
+ The root export (`@lunora/x402`) carries only the shared config/types
18
+ (`X402Network`, `FacilitatorConfig`, price helpers).
15
19
 
16
- ## What is OIDC Trusted Publishing?
20
+ ## Status
17
21
 
18
- OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
22
+ **Both rails shipped.** The **charge** rail gates HTTP-action routes, procedures
23
+ (`.x402({ price })`), and MCP tools behind a USDC price; the **pay** rail signs and
24
+ retries `402` challenges under a mandatory spend policy.
19
25
 
20
- ## Setup Instructions
26
+ ## Networks & custody
21
27
 
22
- To properly configure OIDC trusted publishing for this package:
28
+ - **EVM** (Base, Arbitrum, Ethereum, Polygon, …) is signed via [`@x402/evm`](https://npmjs.com/package/@x402/evm) + [viem](https://viem.sh); pass a raw CAIP-2 id for chains without a friendly alias.
29
+ - **Solana** is signed via [`@x402/svm`](https://npmjs.com/package/@x402/svm).
30
+ - **Facilitator** defaults to the public, Coinbase-operated `https://x402.org/facilitator` (no key required); override it for a self-hosted or CDP facilitator.
23
31
 
24
- 1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
25
- 2. Configure the trusted publisher (e.g., GitHub Actions)
26
- 3. Specify the repository and workflow that should be allowed to publish
27
- 4. Use the configured workflow to publish your actual package
32
+ ### Provider seams
28
33
 
29
- ## DO NOT USE THIS PACKAGE
34
+ Three parts of the exchange are pluggable, and each is chosen independently:
30
35
 
31
- This package is a placeholder for OIDC configuration only. It:
32
- - Contains no executable code
33
- - Provides no functionality
34
- - Should not be installed as a dependency
35
- - Exists only for administrative purposes
36
+ | Seam | Default | How to change it |
37
+ | ------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------- |
38
+ | **Facilitator** | public `https://x402.org/facilitator` | `facilitator: { url, headers }` — self-hosted or a keyed CDP facilitator. |
39
+ | **Wallet custody** | `"raw-key"` (a `ctx.secrets` key, EVM + SVM) | `"cdp"` (Coinbase-managed, EVM) or the `"signer"` escape hatch (any provider you adapt). |
40
+ | **Scheme / chain** | exact scheme picked by `network` (EVM vs SVM) | choose the `network`; `@x402/evm` and `@x402/svm` register the matching exact scheme. |
36
41
 
37
- ## More Information
42
+ The pay rail's `signer` config selects wallet custody:
38
43
 
39
- For more details about npm's trusted publishing feature, see:
40
- - [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
41
- - [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
44
+ - **`{ type: "raw-key", secretName }`** — a self-custodied 32-byte key read from `ctx.secrets`. Works on **EVM and Solana**.
45
+ - **`{ type: "cdp", account }`** — a Coinbase-managed [CDP](https://docs.cdp.coinbase.com) server wallet via the optional [`@coinbase/cdp-sdk`](https://npmjs.com/package/@coinbase/cdp-sdk) peer. The SDK gets-or-creates the named account and signs the EIP-712 authorization, so the key never leaves Coinbase. Wired on **EVM**; the three CDP credentials are read from `ctx.secrets` (`CDP_API_KEY_ID` / `CDP_API_KEY_SECRET` / `CDP_WALLET_SECRET` by default, each overridable). CDP on Solana is not wired (a CDP Solana account is not a `@solana/kit` signer) — use the escape hatch.
46
+ - **`{ type: "signer", signer }`** — the **escape hatch**: hand in a signer you built yourself. Any custody provider (Turnkey, Privy, Fireblocks, an AWS/GCP KMS `toAccount`, CDP's viem adapter, …) works once adapted to the structural EVM (`ClientEvmSigner`) or Solana (`ClientSvmSigner`) shape — so `@lunora/x402` takes no dependency on any provider's SDK. No secret is read.
42
47
 
43
- ---
48
+ > `@coinbase/x402` is a **facilitator-auth** helper, not a custody provider; first-party Coinbase custody is `@coinbase/cdp-sdk`.
44
49
 
45
- **Maintained for OIDC setup purposes only**
50
+ ## Safety
51
+
52
+ The **pay** rail spends real money autonomously. It is `ActionCtx`-only and
53
+ fail-closed: every payment is bounded by a spend policy (per-call and per-window
54
+ caps) and may require confirmation. The `policy` field is required, so you cannot
55
+ wire a signer without one; an unbounded policy is refused at runtime (fail-closed)
56
+ before any signer is resolved.
57
+
58
+ ## License
59
+
60
+ FSL-1.1-Apache-2.0 © [Daniel Bannert](https://github.com/prisis)