@drm3/sdk 0.1.2

package/LICENSE

@@ -0,0 +1,75 @@
+Draft - pending counsel review.
+
+DRM3 SDK License
+
+Copyright 2026 DRM3 Labs Corp. All rights reserved.
+
+This license governs use of the @drm3/sdk software package and the drm3
+command-line tool (together, the "SDK"). By installing or using the SDK, you
+agree to these terms. If you do not agree, do not install or use the SDK.
+
+1. License grant
+
+DRM3 Labs Corp. ("DRM3") grants you a non-exclusive, non-transferable,
+revocable license to install and use the SDK, in its compiled form, solely to
+build and operate applications and agents that integrate with the DRM3 network.
+This grant is limited to the purpose stated in this section and conveys no
+other rights.
+
+2. Restrictions
+
+You may not:
+
+  a. redistribute, resell, sublicense, publish, lease, or otherwise make the
+     SDK available to any third party, in whole or in part;
+
+  b. modify, adapt, translate, reverse engineer, decompile, or disassemble the
+     SDK, or create derivative works from it, except to the limited extent that
+     applicable law expressly permits despite this restriction;
+
+  c. use the SDK to design, build, or operate a product or service that
+     competes with the DRM3 network; or
+
+  d. remove, alter, or obscure any copyright, trademark, or other proprietary
+     notice in or on the SDK.
+
+3. Reservation of rights
+
+The SDK, its interfaces, and its design are the property of DRM3 and are
+protected by intellectual property and other laws. DRM3 reserves all rights not
+expressly granted to you in this license. No title to or ownership of the SDK
+is transferred to you. No rights are granted by implication, estoppel, or
+otherwise beyond those expressly stated here.
+
+4. Feedback
+
+Ideas, feature requests, and issue reports are welcome (see CONTRIBUTING.md).
+Code contributions are not accepted. If you send DRM3 feedback, you grant DRM3
+a perpetual, irrevocable, royalty-free right to use it without restriction or
+obligation to you.
+
+5. No warranty
+
+THE SDK IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NONINFRINGEMENT.
+DRM3 DOES NOT WARRANT THAT THE SDK WILL BE UNINTERRUPTED OR ERROR-FREE.
+
+6. Limitation of liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL DRM3 BE LIABLE FOR
+ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR FOR
+ANY LOSS OF PROFITS, REVENUE, DATA, OR USE, ARISING OUT OF OR IN CONNECTION
+WITH THE SDK OR THIS LICENSE, WHETHER IN CONTRACT, TORT, OR OTHERWISE, EVEN IF
+DRM3 HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+7. Termination
+
+This license is effective until terminated. It terminates automatically if you
+breach any of its terms, and DRM3 may revoke it at any time. On termination,
+you must stop using the SDK and destroy all copies in your possession. Sections
+3 through 8 survive termination.
+
+8. Contact
+
+Inquiries: inquiries@drm3.io

package/README.md

@@ -0,0 +1,426 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/drm3-wordmark-on-dark.png">
+    <img alt="DRM3" src="assets/drm3-wordmark-on-light.png" width="180">
+  </picture>
+</p>
+
+<h1 align="center">@drm3/sdk</h1>
+
+<p align="center">
+  <strong>One package to put an app or an agent on the DRM3 network.</strong>
+</p>
+
+<p align="center">
+  Identity &middot; credits &middot; the x402 payment gateway &middot; partner keys &middot;
+  receipt verification &middot; a cross-app switcher and alerts bell &middot; the <code>drm3</code> CLI.
+</p>
+
+---
+
+## What it is
+
+**The one package to put an app or an agent on the DRM3 network.** Add an account, a credit balance,
+x402 payments, partner keys, and provenance receipts to the code you already have, then ship.
+
+`@drm3/sdk` is a thin, typed client. Identity checks, x402 payments, and receipt chains verify
+**locally** with Web Crypto; everything else is a plain HTTPS call to a DRM3 surface. There is no
+service to host, no daemon, and no sidecar. It ships compiled and typed, and it carries the `drm3`
+CLI for key operations in a terminal. Import a subpath into your code, or run `npx drm3`. That is the
+whole SDK.
+
+## Install
+
+```bash
+npm install @drm3/sdk      # or: pnpm add @drm3/sdk  ·  yarn add @drm3/sdk  ·  bun add @drm3/sdk
+```
+
+TypeScript types are bundled, and the `drm3` CLI installs alongside the library.
+
+## What you need
+
+- **The library**: a JS runtime with `fetch` and Web Crypto (`crypto.subtle`, Ed25519). Every current
+  runtime has both: browsers, Node 20+, Deno, Bun, and edge or serverless runtimes including
+  Cloudflare Workers, Vercel Edge, and Fly or Docker containers.
+- **The `drm3` CLI**: Node 20 or newer.
+- **One runtime dependency**: `@noble/curves` and `@noble/hashes` (audited, zero-dependency crypto).
+  Nothing else.
+
+Install works the same on **Windows, macOS, and Linux**: it is a normal npm package, so if `npm`
+runs, it installs. Module format is ESM with subpath exports and `sideEffects: false`, so a bundler
+ships only the code you import.
+
+## What is in it
+
+Each capability has its own subpath. A server never pulls the browser UI; a browser never pulls the
+Postgres driver.
+
+| Import | What it does | Runs in |
+|--------|--------------|---------|
+| `@drm3/sdk` | Sign-in URLs, the live app catalog, the user's credit balance, Data Passport writes | server or browser |
+| `@drm3/sdk/sso` | Verify the DRM3 identity token locally, per-app launch tokens, a revocation gate | server |
+| `@drm3/sdk/x402` | The x402 "exact" payment gateway: verify a signed payment, build the 402 offer | server |
+| `@drm3/sdk/meter` | Non-custodial credit ledger: authorize / capture / void / settle, plus a multi-bucket wallet | server |
+| `@drm3/sdk/keys` | Partner signing keys: generate, build a CSR, verify a receipt chain to the DRM3 Root | server or browser |
+| `@drm3/sdk/switcher` | The cross-app switcher tile grid, one call | browser |
+| `@drm3/sdk/alerts` | The cross-app alerts bell, one call | browser |
+| `@drm3/sdk/receipts` | The in-browser provenance receipt viewer and a verify button | browser |
+| `drm3` (CLI) | Generate keys, submit a CSR, verify receipts, check partner status | terminal (Node 20+) |
+
+Prebuilt browser bundles ship at `@drm3/sdk/receipts/global` and `@drm3/sdk/alerts/global` for a plain
+`<script>` tag, no bundler required.
+
+## The CLI
+
+The `drm3` CLI is the terminal half of the SDK: the same signing discipline, for a human or an agent
+at a prompt. Zero install with `npx drm3`. It makes an Ed25519 keypair locally (the private key never
+leaves your machine), builds and submits a CSR, verifies a receipt chain to the DRM3 Root, and reads
+live fleet and registry status.
+
+<p align="center">
+  <img src="assets/cli.svg" alt="The drm3 CLI: the help menu, and a keys generate run that prints the public key while the private key is written locally." width="800">
+</p>
+
+```bash
+npx drm3 keys generate --out signing.key   # Ed25519 keypair, private key stays with you
+npx drm3 keys submit --subject my-app --key signing.key
+npx drm3 keys verify receipt.json
+npx drm3 status
+```
+
+## The DRM3 surfaces it talks to
+
+Four surfaces. Most of the SDK runs locally; the network calls are few and cacheable.
+
+| Surface | Host | Used for |
+|---------|------|----------|
+| **Account hub** | `drm3.network` | sign in/out, credit balance, alerts, Passport writes, the revocation feed |
+| **Registry + CA** | `status.drm3.network` | the app catalog, the public key registry, CSR submit and certificate issuance |
+| **Metered inference** | `queue.drm3.network` | the optional shared credit meter |
+| **Base chain** | USDC on Base | where an x402 payment settles, out of band. The SDK never touches it. |
+
+---
+
+## Architecture
+
+The app or agent is the center. It verifies identity, payments, and receipts locally, and makes a
+handful of cacheable calls to the DRM3 surfaces. It never holds a wallet key and never settles money.
+
+```mermaid
+%%{init:{'theme':'base','themeVariables':{'primaryColor':'#EEF2FF','primaryBorderColor':'#3B82F6','lineColor':'#64748B','primaryTextColor':'#1e1b4b','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%%
+flowchart LR
+  U(["Human or agent"])
+  subgraph BOX["Your app or agent + @drm3/sdk"]
+    direction TB
+    ID["sso: verify identity locally"]
+    KEYS["keys: signing + CA"]
+    PAY["x402: verify payments locally"]
+    MET["meter: credit ledger, your DB"]
+    UIX["switcher, alerts, receipts"]
+  end
+  HUB["drm3.network<br/>account hub"]
+  REG["status.drm3.network<br/>registry + CA"]
+  Q["queue.drm3.network<br/>metered inference"]
+  CHAIN["Base chain<br/>USDC"]
+
+  U -->|"sign in / out"| HUB
+  BOX -->|"balance, alerts, Passport, revocations"| HUB
+  BOX -->|"app catalog, public keys, CSR / cert"| REG
+  MET -->|"shared meter (optional)"| Q
+  PAY -.->|"authorization submitted out of band"| CHAIN
+
+  classDef drm3 fill:#EEF2FF,stroke:#3B82F6,color:#1e1b4b;
+  classDef chain fill:#FCE7F3,stroke:#FB3D8E,color:#1e1b4b;
+  class HUB,REG,Q drm3;
+  class CHAIN chain;
+```
+
+---
+
+## The interactions
+
+Every flow, its exact endpoint, and what stays local. Each diagram reads top to bottom.
+
+### Sign in
+
+The user authenticates once at the hub and comes back with a `drm3_sso` token. Your app verifies that
+token locally on every request after that, with no further call to the hub.
+
+```mermaid
+%%{init:{'theme':'base','themeVariables':{'actorBkg':'#EEF2FF','actorBorder':'#3B82F6','actorTextColor':'#1e1b4b','lineColor':'#64748B','noteBkgColor':'#FEF3C7','noteBorderColor':'#FBBF24','noteTextColor':'#1e1b4b'}}}%%
+sequenceDiagram
+  actor U as Human or agent
+  participant App as Your app
+  participant Hub as drm3.network
+  U->>App: click sign in
+  App-->>U: redirect to signInUrl(returnTo)
+  Note over App,Hub: GET /account?login&next=...
+  U->>Hub: authenticate once
+  Hub-->>App: redirect back with a drm3_sso token
+  App->>App: verifySsoToken() runs locally
+```
+
+```ts
+import { createRevocationGate, verifyActiveSsoToken } from "@drm3/sdk/sso";
+
+const gate = createRevocationGate({ url: "https://drm3.network/api/sso/revocations" });
+const claims = await verifyActiveSsoToken(process.env.DRM3_SSO_SECRET!, token, gate);
+if (!claims) return new Response("unauthorized", { status: 401 }); // signature, expiry, revocation, all local
+```
+
+---
+
+### Sign out
+
+One redirect clears the shared session across every DRM3 app, not just yours.
+
+```mermaid
+%%{init:{'theme':'base','themeVariables':{'actorBkg':'#EEF2FF','actorBorder':'#3B82F6','actorTextColor':'#1e1b4b','lineColor':'#64748B'}}}%%
+sequenceDiagram
+  actor U as User
+  participant App as Your app
+  participant Hub as drm3.network
+  U->>App: click sign out
+  App-->>U: redirect to signOutUrl(returnTo)
+  Note over App,Hub: GET /account/signout?next=...
+  Hub->>Hub: clear the shared session
+  Hub-->>App: redirect back, signed out everywhere
+```
+
+---
+
+### Generate a signing key
+
+Fully local. The private key is created on your machine and never leaves it. DRM3 is not contacted.
+
+```mermaid
+%%{init:{'theme':'base','themeVariables':{'actorBkg':'#EEF2FF','actorBorder':'#3B82F6','actorTextColor':'#1e1b4b','noteBkgColor':'#FEF3C7','noteBorderColor':'#FBBF24','noteTextColor':'#1e1b4b'}}}%%
+sequenceDiagram
+  participant You as You (CLI or code)
+  You->>You: generateSigningKey()
+  Note over You: Ed25519 keypair made locally
+  You->>You: store the private key in your secret manager
+```
+
+```bash
+npx drm3 keys generate --out signing.key   # private key stays with you
+```
+
+---
+
+### Get your key certified
+
+You send a self-signed CSR carrying only your public key. A DRM3 operator approves it and the Root
+signs an attestation. DRM3 never sees your private key.
+
+```mermaid
+%%{init:{'theme':'base','themeVariables':{'actorBkg':'#EEF2FF','actorBorder':'#3B82F6','actorTextColor':'#1e1b4b','lineColor':'#64748B','noteBkgColor':'#FEF3C7','noteBorderColor':'#FBBF24','noteTextColor':'#1e1b4b'}}}%%
+sequenceDiagram
+  participant You
+  participant CA as status.drm3.network
+  participant Op as DRM3 operator
+  You->>You: buildCSR({ subject, keyPair })
+  You->>CA: POST /v1/ca/csr (public key only)
+  CA->>Op: queue for approval
+  Op->>CA: approve, the Root signs an attestation
+  You->>CA: GET /v1/ca/cert/:subject
+  CA-->>You: your issuer attestation
+```
+
+```bash
+npx drm3 keys submit --subject my-app --key signing.key
+```
+
+---
+
+### Verify a key or a receipt chain
+
+Anyone can do this. Fetch the public key registry once, then verify the Ed25519 chain locally: a
+receipt links to its issuer attestation, which links to the DRM3 Root.
+
+```mermaid
+%%{init:{'theme':'base','themeVariables':{'actorBkg':'#EEF2FF','actorBorder':'#3B82F6','actorTextColor':'#1e1b4b','lineColor':'#64748B','noteBkgColor':'#FEF3C7','noteBorderColor':'#FBBF24','noteTextColor':'#1e1b4b'}}}%%
+sequenceDiagram
+  participant V as Verifier (anyone)
+  participant Reg as status.drm3.network
+  V->>Reg: GET /.well-known/drm3-keys.json
+  V->>V: verifyChain(receipt, attestation, root)
+  Note over V: receipt to attestation to Root, all local
+```
+
+```bash
+npx drm3 keys verify receipt.json
+```
+
+---
+
+### Read the credit balance
+
+A single call to the hub with the user's identity token.
+
+```mermaid
+%%{init:{'theme':'base','themeVariables':{'actorBkg':'#EEF2FF','actorBorder':'#3B82F6','actorTextColor':'#1e1b4b','lineColor':'#64748B'}}}%%
+sequenceDiagram
+  participant App as Your app
+  participant Hub as drm3.network
+  App->>Hub: GET /api/sso/balance (Bearer drm3_sso)
+  Hub-->>App: { available, credits }
+```
+
+---
+
+### Meter usage
+
+The ledger is yours (SQLite / D1 or Postgres). `authorize` reserves credits and cannot overdraft;
+`capture` settles the real cost and releases the rest. The remote meter is optional, for the shared
+metered-inference path only.
+
+```mermaid
+%%{init:{'theme':'base','themeVariables':{'actorBkg':'#EEF2FF','actorBorder':'#3B82F6','actorTextColor':'#1e1b4b','lineColor':'#64748B'}}}%%
+sequenceDiagram
+  participant App as Your app
+  participant DB as Your DB
+  participant Q as queue.drm3.network (optional)
+  App->>DB: authorize(maxCost) reserve, no overdraft
+  App->>App: do the work, measure the real cost
+  App->>DB: capture(actual) settle, release the hold
+  opt shared metered inference
+    App->>Q: POST /api/internal/meter/charge
+  end
+```
+
+```ts
+import { CreditsClient, InMemoryAdapter } from "@drm3/sdk/meter";
+
+const credits = new CreditsClient({ adapter: new InMemoryAdapter() }); // or a D1 / Postgres adapter
+const auth = await credits.authorize({ tenant: claims.sub, maxCredits: 100n });
+if (!auth.ok) return new Response("payment required", { status: 402 });
+await credits.capture(auth.reservation.id, { credits: 84n });
+```
+
+---
+
+### Alerts
+
+Read the user's cross-app alerts and mark them read. The same bell mounts in any DRM3 app.
+
+```mermaid
+%%{init:{'theme':'base','themeVariables':{'actorBkg':'#EEF2FF','actorBorder':'#3B82F6','actorTextColor':'#1e1b4b','lineColor':'#64748B'}}}%%
+sequenceDiagram
+  participant App as Your app (the bell)
+  participant Hub as drm3.network
+  App->>Hub: GET /api/sso/alerts (Bearer drm3_sso)
+  Hub-->>App: { alerts, unread }
+  App->>Hub: POST /api/sso/alerts/read
+```
+
+---
+
+### Data access (Passport)
+
+The user grants your app a Passport token at the hub's consent screen. Your app then writes into its
+own namespace under the user's record. The hub re-checks the token audience on every write.
+
+```mermaid
+%%{init:{'theme':'base','themeVariables':{'actorBkg':'#EEF2FF','actorBorder':'#3B82F6','actorTextColor':'#1e1b4b','lineColor':'#64748B','noteBkgColor':'#FEF3C7','noteBorderColor':'#FBBF24','noteTextColor':'#1e1b4b'}}}%%
+sequenceDiagram
+  actor U as User
+  participant App as Your app
+  participant Hub as drm3.network
+  U->>Hub: grant a Passport token (consent)
+  App->>Hub: POST /api/passport/app-write (Bearer passport)
+  Note over App,Hub: writes app.{clientId}.{slug}
+```
+
+---
+
+### x402 payment
+
+Your app answers `402` with an offer. The agent signs an EIP-3009 authorization to `payTo` and retries.
+`verifyX402Payment` checks the signature locally: it holds no key and broadcasts nothing. **Settlement
+is out of band** - the signed authorization is submitted on-chain by the caller or a facilitator, which
+moves USDC directly to `payTo`. The SDK does not settle and never custodies funds.
+
+```mermaid
+%%{init:{'theme':'base','themeVariables':{'actorBkg':'#EEF2FF','actorBorder':'#3B82F6','actorTextColor':'#1e1b4b','lineColor':'#64748B','noteBkgColor':'#FCE7F3','noteBorderColor':'#FB3D8E','noteTextColor':'#1e1b4b'}}}%%
+sequenceDiagram
+  actor A as Paying agent
+  participant App as Your app
+  participant Chain as Base (USDC)
+  A->>App: request, no payment
+  App-->>A: 402 + the offer
+  A->>A: sign an EIP-3009 authorization to payTo
+  A->>App: retry with the X-PAYMENT header
+  App->>App: verifyX402Payment() local, no key
+  App->>App: your nonce-replay gate
+  App-->>A: 200 + the resource
+  A-)Chain: submit authorization (out of band)
+```
+
+```ts
+import { verifyX402Payment, x402Body } from "@drm3/sdk/x402";
+
+const cfg = { payTo: process.env.X402_PAY_TO!, priceAtomic: 10_000n }; // 0.01 USDC on Base
+const header = req.headers.get("x-payment");
+if (!header) return Response.json(x402Body(cfg, { resource: "/answer", description: "One answer" }), { status: 402 });
+
+const result = verifyX402Payment(header, cfg); // pure, holds no key
+if (!result.ok) return new Response(result.error, { status: 402 });
+// result.payer is recovered from the signature. Run your nonce-replay gate, then serve.
+```
+
+---
+
+### Offers
+
+`x402Body` builds the `402` menu. `accepts` is the machine-payable x402 requirement; `offers` and
+`hint` are additive extras for humans and apps, and x402 clients ignore them.
+
+```mermaid
+%%{init:{'theme':'base','themeVariables':{'actorBkg':'#EEF2FF','actorBorder':'#3B82F6','actorTextColor':'#1e1b4b','lineColor':'#64748B'}}}%%
+sequenceDiagram
+  participant App as Your app
+  participant A as Caller
+  App->>App: x402Body(cfg, { resource, description, offers, hint })
+  App-->>A: 402 with accepts + optional offers + hint
+```
+
+---
+
+## Browser drop-ins
+
+Three one-call widgets. Mount them into an element and they render, fetch, and stay in sync.
+
+```ts
+import { mountAppSwitcher } from "@drm3/sdk/switcher";
+import { mountAlertsBell } from "@drm3/sdk/alerts";
+import { mountVerifyButton } from "@drm3/sdk/receipts";
+
+mountAppSwitcher(document.getElementById("switcher"));
+mountAlertsBell(document.getElementById("bell"));
+mountVerifyButton(document.getElementById("verify"), { receiptId });
+```
+
+## For agents and LLMs
+
+An agent puts itself on the network the same way an app does: `npm install @drm3/sdk`, then import the
+one subpath it needs. For keys, run `npx drm3 keys generate --out signing.key` (the private key stays
+local) and verify receipt chains with `npx drm3 keys verify`. To pay an x402-gated endpoint, sign an
+EIP-3009 authorization to the offer's `payTo` and retry with the `X-PAYMENT` header.
+
+A machine-readable summary of the package, its subpaths, the CLI, and the DRM3 surfaces lives in
+[`llms.txt`](./llms.txt).
+
+## Feedback and submissions
+
+We do not accept pull requests or code contributions: the SDK is source-managed by DRM3 Labs Corp. so
+every app and agent on the network shares one signed, tested surface. We do want your ideas, feature
+requests, and bug reports. Open a GitHub issue on this repository, or email inquiries@drm3.io. See
+[CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Legal
+
+`@drm3/sdk` is proprietary software under the **DRM3 SDK License**, Copyright 2026 DRM3 Labs Corp., all
+rights reserved. It is licensed for use to build and operate applications and agents that integrate
+with the DRM3 network; the SDK, its interfaces, and its design are DRM3 Labs Corp. intellectual
+property. See [LICENSE](./LICENSE). Inquiries: inquiries@drm3.io.