@wopr-network/platform-core 1.17.0 → 1.18.0

package/dist/billing/crypto/evm/__tests__/config.test.js

@@ -19,6 +19,16 @@ describe("getTokenConfig", () => {
         expect(cfg.contractAddress).toMatch(/^0x/);
         expect(cfg.contractAddress).toBe("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
     });
+    it("returns USDT on Base", () => {
+        const cfg = getTokenConfig("USDT", "base");
+        expect(cfg.decimals).toBe(6);
+        expect(cfg.contractAddress).toBe("0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2");
+    });
+    it("returns DAI on Base", () => {
+        const cfg = getTokenConfig("DAI", "base");
+        expect(cfg.decimals).toBe(18);
+        expect(cfg.contractAddress).toBe("0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb");
+    });
     it("throws on unsupported token/chain combo", () => {
         // biome-ignore lint/suspicious/noExplicitAny: testing invalid input
         expect(() => getTokenConfig("USDC", "ethereum")).toThrow("Unsupported token");

package/dist/billing/crypto/evm/config.js

@@ -14,6 +14,18 @@ const TOKENS = {
         contractAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
         decimals: 6,
     },
+    "USDT:base": {
+        token: "USDT",
+        chain: "base",
+        contractAddress: "0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2",
+        decimals: 6,
+    },
+    "DAI:base": {
+        token: "DAI",
+        chain: "base",
+        contractAddress: "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
+        decimals: 18,
+    },
 };
 export function getChainConfig(chain) {
     const cfg = CHAINS[chain];

package/dist/billing/crypto/evm/types.d.ts

@@ -1,7 +1,7 @@
 /** Supported EVM chains. */
 export type EvmChain = "base";
 /** Supported stablecoin tokens. */
-export type StablecoinToken = "USDC";
+export type StablecoinToken = "USDC" | "USDT" | "DAI";
 /** Chain configuration. */
 export interface ChainConfig {
     readonly chain: EvmChain;

package/docs/superpowers/specs/2026-03-14-fleet-auto-update-design.md

@@ -0,0 +1,300 @@
+# Fleet Auto-Update with Rolling Waves
+
+**Date:** 2026-03-14
+**Status:** Draft
+**Repos:** platform-core, paperclip, paperclip-platform, paperclip-platform-ui
+
+## Problem
+
+Upstream Paperclip changes land nightly via `upstream-sync.mjs`, which rebases our fork and creates a PR. After manual review and merge, `docker-managed.yml` auto-builds and pushes `ghcr.io/wopr-network/paperclip:managed`. But existing running containers never receive the update. New containers get `:managed` on first pull; old containers are stuck on whatever digest they were created with.
+
+platform-core has `ImagePoller` and `ContainerUpdater` classes that are fully implemented and tested but **not wired into the application lifecycle**.
+
+## Design
+
+### Pipeline Overview
+
+```
+paperclipai/paperclip (upstream)
+    | nightly 06:00 UTC
+upstream-sync.mjs (rebase + hostedMode guards + changelog generation)
+    | creates PR
+human reviews & merges PR
+    | push to master
+docker-managed.yml (auto-build)
+    | pushes ghcr.io/wopr-network/paperclip:managed
+ImagePoller detects new digest
+    | groups bots by tenant
+RolloutOrchestrator executes strategy
+    | per-bot update sequence
+ContainerUpdater (snapshot + pull + recreate + health check + rollback)
+```
+
+### Human Gate
+
+The only human checkpoint is **reviewing and merging the upstream sync PR**. Everything downstream is automatic.
+
+### 1. Changelog Generation (changes to `paperclip/scripts/upstream-sync.mjs`)
+
+After rebase and hostedMode gap scanning, the sync agent generates two changelogs:
+
+**Internal changelog** (`changelogs/internal/YYYY-MM-DD.md`):
+- Full developer-facing diff summary
+- What upstream changed, what guards were added, conflicts resolved
+- For PR review purposes
+
+**User-facing changelog** (`changelogs/user-facing/YYYY-MM-DD.json`):
+- Structured format: `{ version, date, sections: [{ title: "New" | "Improved" | "Fixed", items: string[] }] }`
+- Filtered through hosted-mode exclusion list — silently drops anything related to: adapters, model selection, thinking effort, runtime/heartbeat config, provider API keys, CLI, deployment modes, infrastructure, self-hosting
+- Same `HOSTED_MODE_CONTEXT` that drives the guard scanner drives the changelog filter
+
+Both files are committed in the sync PR. The user-facing JSON is copied into the Docker image during build (add `COPY changelogs/user-facing/ /app/changelogs/` to `Dockerfile.managed`). If the image exists, its changelog exists.
+
+**Changelog retrieval:** After pulling a new image (before starting the update sequence), extract the changelog:
+
+```bash
+docker run --rm ghcr.io/wopr-network/paperclip:managed cat /app/changelogs/latest.json
+```
+
+The extracted JSON is stored in the fleet event payload for email and UI consumption. The `latest.json` symlink always points to the most recent changelog file.
+
+### 2. Image Detection (wire existing code in `platform-core`)
+
+Changes to `src/fleet/services.ts`:
+
+- Add `ImagePoller` and `ContainerUpdater` singletons
+- `initFleet()` starts the poller and wires `poller.onUpdateAvailable` to `RolloutOrchestrator`
+- ImagePoller already handles poll intervals per release channel (canary=5m, staging=15m, stable=30m)
+
+### 3. Rollout Orchestrator (new: `src/fleet/rollout-orchestrator.ts`)
+
+GoF Strategy pattern. The orchestrator is the context; strategies are interchangeable.
+
+**`IRolloutStrategy` interface:**
+
+```typescript
+interface IRolloutStrategy {
+  /** Select next batch from remaining bots */
+  nextBatch(remaining: BotProfile[]): BotProfile[];
+  /** Milliseconds to wait between waves */
+  pauseDuration(): number;
+  /** What to do when a single bot update fails */
+  onBotFailure(botId: string, error: Error, attempt: number): "abort" | "skip" | "retry";
+  /** Max retries per bot before skip/abort */
+  maxRetries(): number;
+  /** Health check timeout per bot (ms) */
+  healthCheckTimeout(): number;
+}
+```
+
+**Concrete strategies:**
+
+| Strategy | Batch | Pause | Failure | Use Case |
+|----------|-------|-------|---------|----------|
+| `RollingWaveStrategy` | configurable % | configurable | abort on N+ failures | Default for auto-update |
+| `SingleBotStrategy` | 1 bot | N/A | report | Manual per-bot update button |
+| `ImmediateStrategy` | all | 0 | skip | Emergency hotfix |
+
+Strategy selection is **admin-controlled only** — users never see this.
+
+**Orchestrator flow:**
+
+```
+1. Group update-eligible bots by tenant
+2. For each tenant:
+   a. Check tenant update mode (auto/manual)
+   b. If manual: mark bots as "update available", send notification, stop
+   c. If auto: check if current time is within tenant's preferred window
+   d. Select strategy (from admin config)
+   e. Execute waves:
+      - batch = strategy.nextBatch(remaining)
+      - for each bot in batch: ContainerUpdater.updateBot()
+      - if any failure: strategy.onBotFailure() → abort/skip/retry
+      - sleep(strategy.pauseDuration())
+      - repeat until remaining is empty
+3. Send notification emails with changelog
+```
+
+### 4. Update Sequence Per Bot (major rework of `ContainerUpdater`)
+
+Nuclear rollback — image AND volumes roll back together.
+
+**Volume Snapshot Mechanism (new: `VolumeSnapshotManager`):**
+
+The existing `SnapshotManager` operates on filesystem paths, not Docker named volumes. A new `VolumeSnapshotManager` is needed that snapshots Docker named volumes using a temporary container:
+
+```bash
+# Snapshot a named volume to a tar archive:
+docker run --rm -v <volume-name>:/source -v <backup-dir>:/backup alpine \
+  tar cf /backup/<volume-name>-<timestamp>.tar -C /source .
+
+# Restore a named volume from a tar archive:
+docker run --rm -v <volume-name>:/target -v <backup-dir>:/backup alpine \
+  sh -c "rm -rf /target/* && tar xf /backup/<volume-name>-<timestamp>.tar -C /target"
+```
+
+This is a new class (`src/fleet/volume-snapshot-manager.ts`), not a modification of the existing `SnapshotManager`.
+
+**Update sequence:**
+
+```
+1. Snapshot /data and /paperclip volumes (via VolumeSnapshotManager)
+2. Record previous image digest (already implemented)
+3. Pull new image
+4. Stop container
+5. Recreate container with new image (named volumes remount automatically)
+6. Start container (PAPERCLIP_MIGRATION_AUTO_APPLY=true runs Drizzle migrations on boot)
+7. Health check: HTTP GET http://container:3100/health, expect {"status":"ok"}
+   - Timeout: 120s (increased from current 60s to allow for Drizzle migration time)
+   - Poll interval: 5s
+8a. HEALTHY:
+   - Delete volume snapshots
+   - Emit fleet event: bot.updated
+   - Record new digest
+8b. UNHEALTHY:
+   - Stop container
+   - Restore volume snapshots from step 1 (via VolumeSnapshotManager)
+   - Recreate container with OLD image (digest-pinned to prevent re-pulling new)
+   - Start container
+   - Verify old container is healthy
+   - Emit fleet event: bot.update_failed
+   - Report to orchestrator (abort/skip/retry per strategy)
+```
+
+**Health check upgrade:** Replace `node -e 'process.exit(0)'` in `createContainer()` with:
+
+```typescript
+Healthcheck: {
+  // Use node+fetch instead of curl — Paperclip's base image (node:lts-trixie-slim)
+  // may not have curl installed.
+  Test: ["CMD-SHELL", "node -e \"fetch('http://localhost:3100/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""],
+  Interval: 30_000_000_000,
+  Timeout: 10_000_000_000,
+  Retries: 3,
+  StartPeriod: 60_000_000_000, // 60s for Drizzle migrations on boot
+}
+```
+
+**Note:** `HEALTH_CHECK_TIMEOUT_MS` in `ContainerUpdater` must be increased from 60,000 to 120,000 to match the spec's 120s timeout.
+
+### 5. Tenant Update Config
+
+Stored per-tenant (moves to per-org when org support ships — see `2026-03-14-paperclip-org-integration-design.md`).
+
+```typescript
+interface TenantUpdateConfig {
+  /** "auto" = rolling wave in preferred window; "manual" = badge + button */
+  mode: "auto" | "manual";
+  /** Hour of day (UTC) for auto-update window. Only used when mode=auto. */
+  preferredHourUtc: number; // 0-23, default 3
+}
+```
+
+Default for new tenants: `{ mode: "manual", preferredHourUtc: 3 }`.
+
+**Repository interface** (follows the `IFooRepository` pattern used throughout platform-core):
+
+```typescript
+export interface ITenantUpdateConfigRepository {
+  get(tenantId: string): Promise<TenantUpdateConfig | null>;
+  upsert(tenantId: string, config: TenantUpdateConfig): Promise<void>;
+  listAutoEnabled(): Promise<Array<{ tenantId: string; config: TenantUpdateConfig }>>;
+}
+```
+
+`DrizzleTenantUpdateConfigRepository` implements this against a `tenant_update_configs` table with columns `(tenant_id TEXT PK, mode TEXT, preferred_hour_utc INTEGER, updated_at BIGINT)`.
+
+**Audit logging:** All config changes (mode switch, hour change) are logged via `logger.info("Tenant update config changed", { tenantId, oldConfig, newConfig, actorUserId })`. Admin-triggered updates via the `/admin/updates` route include the actor in the log entry.
+
+Admin panel can override per-tenant or set global defaults.
+
+**Precedence: tenant config overrides per-bot `updatePolicy`.** The existing `BotProfile.updatePolicy` field (per-bot: `on-push`, `nightly`, `manual`, `cron:*`) is superseded by `TenantUpdateConfig` for hosted deployments. The `RolloutOrchestrator` reads tenant config, not bot-level policy. `ImagePoller.shouldAutoUpdate()` is refactored to always return `false` — the poller's only job is to detect new digests and notify the orchestrator, which makes the auto/manual decision based on tenant config.
+
+`ImagePoller.isNightlyWindow()` (hardcoded 03:00-03:30 UTC) is superseded by the orchestrator's per-tenant `preferredHourUtc` window check. The poller's nightly logic becomes a no-op.
+
+Per-bot `updatePolicy` is preserved in the schema for self-hosted (non-platform) deployments where there is no tenant config.
+
+### 6. Admin Controls
+
+Admin panel (platform-core admin routes, not user-facing):
+
+- **Global update mode**: auto / manual / paused (pause halts all rollouts fleet-wide)
+- **Strategy config**: batch %, pause duration, failure threshold
+- **Default update window**: hour UTC
+- **Per-tenant overrides**: mode, window
+- **Manual triggers**: "roll out now" for a specific image digest
+- **Rollout status dashboard**: which bots updated, which failed, which pending
+
+### 7. User-Facing Experience
+
+**Auto mode (tenant doesn't know or care):**
+- Updates happen silently during configured window
+- Email after: "Your Paperclip was updated. Here's what's new: [changelog]"
+- Brief downtime during container restart (seconds)
+
+**Manual mode:**
+- Email when update available: "A new update is available for your Paperclip. [changelog]"
+- In-app: badge on bot in UI indicating update available
+- Click "Update" → modal shows user-facing changelog with "Update Now" / "Later" buttons
+- "Update Now" triggers `SingleBotStrategy` immediately
+- Email after: "Your Paperclip was updated. Here's what's new: [changelog]"
+
+**Both modes:**
+- Admin email on rollback failure
+- Fleet event log for audit
+
+### 8. Image Allowlist
+
+`FLEET_IMAGE_ALLOWLIST` already allows `ghcr.io/wopr-network/` — covers both WOPR and Paperclip images. Future brands add their prefix.
+
+## Files to Create/Modify
+
+### platform-core
+
+| File | Action | Description |
+|------|--------|-------------|
+| `src/fleet/rollout-orchestrator.ts` | Create | Strategy pattern orchestrator |
+| `src/fleet/rollout-strategies.ts` | Create | RollingWave, SingleBot, Immediate strategies |
+| `src/fleet/services.ts` | Modify | Wire ImagePoller + ContainerUpdater + RolloutOrchestrator into initFleet() |
+| `src/fleet/updater.ts` | Major rework | Add volume snapshot/restore lifecycle, replace FleetManager delegation with direct Docker operations for atomic update, upgrade health check from Docker HEALTHCHECK polling to HTTP GET, increase timeout from 60s to 120s |
+| `src/fleet/volume-snapshot-manager.ts` | Create | Snapshot and restore Docker named volumes using temporary alpine containers |
+| `src/fleet/fleet-manager.ts` | Modify | Upgrade HEALTHCHECK in createContainer() to use node+fetch instead of node -e |
+| `src/fleet/image-poller.ts` | Modify | Wire onUpdateAvailable to orchestrator instead of direct updater |
+| `src/db/schema/tenant-update-config.ts` | Create | Drizzle schema for tenant update preferences |
+| `src/api/routes/admin-updates.ts` | Create | Admin API for update management |
+| `src/fleet/update-notifier.ts` | Create | Email notifications for updates |
+
+### paperclip
+
+| File | Action | Description |
+|------|--------|-------------|
+| `scripts/upstream-sync.mjs` | Modify | Add changelog generation step |
+| `Dockerfile.managed` | Modify | COPY changelogs into image |
+| `changelogs/` | Create | Directory for generated changelogs |
+
+### paperclip-platform-ui
+
+| File | Action | Description |
+|------|--------|-------------|
+| Update modal component | Create | Shows changelog, "Update Now" / "Later" |
+| Bot card badge | Modify | Show "Update Available" indicator |
+
+## Dependencies
+
+- **Implementation work required:**
+  - `ImagePoller` and `ContainerUpdater` classes exist and are tested, but have no singleton getters in `services.ts` and are not imported or wired. Docker instance injection needs to be plumbed through.
+  - `ContainerUpdater` needs significant enhancement: volume snapshot/restore integration with `SnapshotManager`, HTTP-based health checks (replacing `node -e`), increased timeout from 60s to 120s for migration time.
+  - `RolloutOrchestrator` and strategies are entirely new code.
+  - `SnapshotManager` exists in `src/backup/` but has no integration with `ContainerUpdater`.
+- **Future:** Org support (see `2026-03-14-paperclip-org-integration-design.md`) — update config moves from tenant to org level after org integration ships
+- **Future:** Cron policy implementation in ImagePoller (currently stubbed)
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Bad upstream migration corrupts data | Nuclear rollback: volume snapshot restored alongside image rollback |
+| Upstream pushes breaking change | Human gate at sync PR review catches this before any image is built |
+| Rolling wave takes too long | ImmediateStrategy available for emergency hotfixes |
+| Health check passes but app is subtly broken | `/health` endpoint queries DB, so migration failures surface. Consider adding deeper health checks later. |
+| Volume snapshots consume disk | Snapshots deleted after successful update. Failed rollbacks alert admin for manual cleanup. |

package/docs/superpowers/specs/2026-03-14-paperclip-org-integration-design.md

@@ -0,0 +1,359 @@
+# Paperclip Platform Org Integration
+
+**Date:** 2026-03-14
+**Status:** Draft
+**Repos:** paperclip, paperclip-platform, paperclip-platform-ui, platform-core, platform-ui-core
+
+## Problem
+
+Paperclip (the bot) has a full multi-user org model: companies, memberships, invites, roles, permissions, org charts. The hosted platform layer (paperclip-platform + paperclip-platform-ui) also has an org model: tenants, organization_members, organization_invites.
+
+Today the managed Paperclip image runs in `local_trusted` mode, which hardcodes every request as `userId: "local-board"` with instance admin privileges. There is no user identity inside the bot — everyone is the same person.
+
+The platform is the front door: it handles auth, billing, and access. Users should manage their team exclusively through the platform. Paperclip's native invite/member UI should be hidden in hosted mode.
+
+When a user is invited to a platform org, they should be able to use the Paperclip instance immediately — no second signup, no separate invite flow inside the bot.
+
+## Design
+
+### Architecture
+
+```
+Platform (front door)
+  ├─ Auth (better-auth sessions)
+  ├─ Org management (invite, roles, billing)
+  ├─ Proxy (routes requests to Paperclip container)
+  │   └─ Injects: x-platform-user-id, x-platform-user-email, x-platform-user-name
+  └─ Provisioning (syncs membership changes into Paperclip)
+      └─ Calls /internal/add-member, /internal/remove-member
+
+Paperclip (the bot, hosted_proxy mode)
+  ├─ actorMiddleware reads proxy headers → resolves user identity
+  ├─ Company/invite/member UI hidden in hostedMode
+  └─ All org management delegated to platform
+```
+
+### 1. New Deployment Mode: `hosted_proxy`
+
+**File:** `paperclip/server/src/middleware/auth.ts`
+
+Add a new branch in `actorMiddleware` for `hosted_proxy` deployment mode. Instead of hardcoding `local-board`, read identity from trusted proxy headers:
+
+```typescript
+if (opts.deploymentMode === "hosted_proxy") {
+  const userId = req.header("x-platform-user-id");
+  const userEmail = req.header("x-platform-user-email");
+  const userName = req.header("x-platform-user-name");
+
+  if (userId) {
+    const [roleRow, memberships] = await Promise.all([
+      db.select({ id: instanceUserRoles.id })
+        .from(instanceUserRoles)
+        .where(and(
+          eq(instanceUserRoles.userId, userId),
+          eq(instanceUserRoles.role, "instance_admin")
+        ))
+        .then(rows => rows[0] ?? null),
+      db.select({ companyId: companyMemberships.companyId })
+        .from(companyMemberships)
+        .where(and(
+          eq(companyMemberships.principalType, "user"),
+          eq(companyMemberships.principalId, userId),
+          eq(companyMemberships.status, "active"),
+        )),
+    ]);
+
+    req.actor = {
+      type: "board",
+      userId,
+      companyIds: memberships.map(r => r.companyId),
+      isInstanceAdmin: Boolean(roleRow),
+      source: "hosted_proxy",
+    };
+  } else {
+    // No user header = reject (proxy should always inject)
+    req.actor = { type: "none", source: "none" };
+  }
+}
+```
+
+**Dockerfile.managed change:** `PAPERCLIP_DEPLOYMENT_MODE=hosted_proxy` (was `local_trusted`)
+
+**Security:** The container is never exposed to the internet. Only the platform proxy can reach it. Trusting headers from the proxy is safe — same pattern as any reverse proxy auth.
+
+### 2. Provision Endpoints for Member Management
+
+**File:** `paperclip/server/src/routes/provision.ts` (extend existing adapter)
+
+The provision adapter already has `ensureUser()` and `grantAccess()`. Add new operations to the adapter interface:
+
+**Role mapping (platform → Paperclip):**
+
+| Platform Role | Paperclip Role | Instance Admin | Notes |
+|--------------|----------------|----------------|-------|
+| `owner` | `owner` | Yes | Full control |
+| `admin` | `owner` | Yes | Same as owner inside Paperclip — admin distinction is platform-level (billing, org settings) |
+| `member` | `member` | No | Can view/create issues, interact with agents |
+
+**Add member:**
+```typescript
+async addMember(companyId: string, user: AdminUser, role: "owner" | "admin" | "member") {
+  await this.ensureUser(user);
+  const paperclipRole = role === "member" ? "member" : "owner";
+  await access.ensureMembership(companyId, "user", user.id, paperclipRole, "active");
+  if (paperclipRole === "owner") {
+    await access.promoteInstanceAdmin(user.id);
+  }
+}
+```
+
+**Remove member:**
+```typescript
+async removeMember(companyId: string, userId: string) {
+  // Remove company membership
+  await access.removeMembership(companyId, "user", userId);
+  // Demote instance admin if no longer owner of any company
+  const remaining = await access.listUserCompanyAccess(userId);
+  if (remaining.length === 0) {
+    await access.demoteInstanceAdmin(userId);
+  }
+}
+```
+
+**Change role:**
+```typescript
+async changeRole(companyId: string, userId: string, role: "owner" | "admin" | "member") {
+  const paperclipRole = role === "member" ? "member" : "owner";
+  await access.ensureMembership(companyId, "user", userId, paperclipRole, "active");
+  if (paperclipRole === "owner") {
+    await access.promoteInstanceAdmin(userId);
+  } else {
+    // Demotion: remove instance admin if user is no longer owner of any company
+    const remaining = await access.listUserCompanyAccess(userId);
+    const isOwnerOfAny = remaining.some(c => c.role === "owner");
+    if (!isOwnerOfAny) {
+      await access.demoteInstanceAdmin(userId);
+    }
+  }
+}
+```
+
+These map to new provision-server routes:
+- `POST /internal/members/add` — `{ companyId, user: { id, email, name }, role }`
+- `POST /internal/members/remove` — `{ companyId, userId }`
+- `POST /internal/members/change-role` — `{ companyId, userId, role }`
+
+**All provision endpoints are idempotent.** Repeated calls with the same parameters are no-ops (`ensureUser` checks for existing records, `ensureMembership` upserts).
+
+All authenticated via `PROVISION_SECRET` bearer token (brand-agnostic; replaces the WOPR-specific `WOPR_PROVISION_SECRET` naming).
+
+### 3. Platform Triggers Provisioning on Org Changes
+
+**File:** `paperclip-platform/src/trpc/routers/org.ts`
+
+When org membership changes happen in the platform, call the Paperclip instance's provision API:
+
+**Invite accepted → add member** (triggered from `acceptInvite()` in org.ts — see Section 5):
+```
+Platform: user accepts org invite
+  → acceptInvite() adds user to organization_members
+  → acceptInvite() resolves tenant's Paperclip instance
+  → POST instance:3100/internal/members/add
+    { companyId: <paperclip company id>, user: { id, email, name }, role: "member" }
+```
+
+**Member removed → remove member:**
+```
+Platform: admin removes member from org
+  → platform removes from organization_members
+  → POST instance:3100/internal/members/remove
+    { companyId: <paperclip company id>, userId }
+```
+
+**Role changed → change role:**
+```
+Platform: admin changes member role
+  → platform updates organization_members
+  → POST instance:3100/internal/members/change-role
+    { companyId: <paperclip company id>, userId, role }
+```
+
+**Mapping:** Platform org → Paperclip company. The `companyId` is stored during initial provisioning (already returned by `createTenant()`). Platform stores this mapping in the tenant record.
+
+### 4. Hide Company/Invite/Member UI in Hosted Mode
+
+**File:** `paperclip/scripts/upstream-sync.mjs`
+
+Expand the `infraKeywords` list in `scanForHostedModeGaps()` to include org management patterns:
+
+```javascript
+const infraKeywords = [
+  // Existing adapter/model keywords...
+  "adapterType", "AdapterType", /* ... */
+
+  // NEW: Org management keywords (hidden in hosted mode)
+  "CompanySettings",
+  "CompanySwitcher",
+  "InviteLanding",
+  "createInvite",
+  "inviteLink",
+  "joinRequest",
+  "companyMemberships",
+  "boardClaim",
+  "BoardClaim",
+  "manageMembers",
+  "instanceSettings",
+];
+```
+
+**Specific UI changes needed in Paperclip:**
+
+| File | Action |
+|------|--------|
+| `ui/src/pages/CompanySettings.tsx` | Hide invite creation, member management sections in hostedMode |
+| `ui/src/components/CompanySwitcher.tsx` | Hide "Manage Companies" link, hide "Company Settings" link in hostedMode |
+| `ui/src/pages/Companies.tsx` | Hide create/delete company in hostedMode (single company, platform-managed) |
+| `ui/src/pages/InviteLanding.tsx` | Redirect to platform in hostedMode |
+| `ui/src/pages/BoardClaim.tsx` | Redirect to platform in hostedMode |
+| `ui/src/components/Layout.tsx` | Hide any "Invite" buttons in hostedMode |
+
+**What stays visible:** The Org page (org chart, agent hierarchy) and agent management stay visible — those are product features, not org admin. Users can still see who's on the team and what agents are doing.
+
+### 5. Platform Org Gaps to Fix
+
+These are existing stubs/gaps in paperclip-platform that need implementation:
+
+**`listMyOrganizations()` (org.ts):**
+Currently returns empty. Implement: query `organization_members` for user's memberships, return list of orgs.
+
+**Invite acceptance flow:**
+`inviteMember()` creates the invite, but there's no `acceptInvite()` endpoint. Implement:
+1. Validate token, check not expired/revoked
+2. Create user account if needed (signup during accept)
+3. Add to `organization_members`
+4. Call Paperclip provision API to add member (triggers the flow described in Section 3)
+5. Mark invite as accepted
+
+**`listMyOrganizations()`:** Currently returns empty in org.ts. Implement by adding `listOrgsForUser(userId)` to platform-core's `OrgService`, then calling it from the tRPC route.
+
+**Org switcher in platform UI:**
+`x-tenant-id` header mechanism exists but isn't exposed in the frontend. Add org switcher component that:
+- Lists user's orgs
+- Switches `x-tenant-id` header for subsequent API calls
+- Persists selection to localStorage
+
+**Member list population:**
+Org member list loads but doesn't populate user name/email. Join `organization_members` with user table to get display info.
+
+### 6. Proxy Header Injection
+
+**File:** `paperclip-platform/src/proxy/tenant-proxy.ts`
+
+The platform proxy already routes requests to Paperclip containers. Add header injection:
+
+```typescript
+// Before proxying to the Paperclip container:
+proxyReq.setHeader("x-platform-user-id", ctx.user.id);
+proxyReq.setHeader("x-platform-user-email", ctx.user.email);
+proxyReq.setHeader("x-platform-user-name", ctx.user.name ?? "");
+```
+
+Strip these headers from incoming external requests to prevent spoofing:
+```typescript
+// On incoming request, before auth:
+req.headers.delete("x-platform-user-id");
+req.headers.delete("x-platform-user-email");
+req.headers.delete("x-platform-user-name");
+```
+
+## User Experience
+
+### Inviting a Teammate
+
+1. User goes to Platform → Settings → Team
+2. Clicks "Invite Member"
+3. Enters email, selects role (admin/member)
+4. Invitee receives email with signup/accept link
+5. Invitee creates platform account (or logs in if existing)
+6. Platform adds them to org + provisions into Paperclip instance
+7. Invitee logs in → sees the Paperclip workspace with full access
+
+### Day-to-Day Usage
+
+- User logs into platform
+- Platform authenticates, resolves org context
+- User clicks into their Paperclip instance
+- Every request carries their identity via proxy headers
+- Paperclip shows their issues, their agents, their activity
+- Team members see the same company but actions are attributed to the right person
+
+### What Users Never See
+
+- Paperclip's native invite flow
+- Paperclip's company management
+- Paperclip's member management
+- Any awareness that two systems exist
+
+## Files to Create/Modify
+
+### paperclip (the bot)
+
+| File | Action | Description |
+|------|--------|-------------|
+| `server/src/middleware/auth.ts` | Modify | Add `hosted_proxy` deployment mode branch |
+| `server/src/routes/provision.ts` | Modify | Add addMember, removeMember, changeRole to adapter |
+| `Dockerfile.managed` | Modify | Change PAPERCLIP_DEPLOYMENT_MODE to hosted_proxy |
+| `scripts/upstream-sync.mjs` | Modify | Expand infraKeywords for org management patterns |
+| `ui/src/pages/CompanySettings.tsx` | Modify | Add hostedMode guards for invite/member sections |
+| `ui/src/components/CompanySwitcher.tsx` | Modify | Hide management links in hostedMode |
+| `ui/src/pages/Companies.tsx` | Modify | Hide create/delete in hostedMode |
+| `ui/src/pages/InviteLanding.tsx` | Modify | Redirect to platform in hostedMode |
+| `ui/src/pages/BoardClaim.tsx` | Modify | Redirect to platform in hostedMode |
+| `packages/shared/src/types.ts` | Modify | Add "hosted_proxy" to DeploymentMode union |
+
+### paperclip-platform
+
+| File | Action | Description |
+|------|--------|-------------|
+| `src/trpc/routers/org.ts` | Modify | Implement listMyOrganizations, acceptInvite, wire provisioning calls |
+| `src/proxy/tenant-proxy.ts` | Modify | Inject + strip x-platform-user-* headers |
+| `src/fleet/provision-client.ts` | Modify | Add addMember, removeMember, changeRole methods |
+
+### platform-ui-core
+
+| File | Action | Description |
+|------|--------|-------------|
+| Org switcher component | Create | Switch between orgs, set x-tenant-id |
+| Invite acceptance page | Create | Accept invite → create account → join org |
+| Member list | Modify | Populate user name/email from joined query |
+
+### platform-core
+
+| File | Action | Description |
+|------|--------|-------------|
+| `src/tenancy/org-service.ts` | Modify | Add listOrgsForUser(userId), acceptInvite(token) |
+| provision-server package | Modify | Add member management routes to protocol |
+
+## Dependencies
+
+- **Blocks:** Fleet auto-update org-level config (currently tenant-level, moves to org-level after this ships)
+- **Requires:** provision-server package update for new member management routes
+- **Requires:** `@paperclipai/shared` types update for `hosted_proxy` deployment mode
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Upstream adds new invite/member UI patterns | Upstream sync scanner catches them via expanded keyword list |
+| Provisioning call fails when adding member | Retry with backoff. Member shows in platform but can't access Paperclip until sync succeeds. Show "provisioning" state in UI. |
+| Header spoofing | Strip x-platform-user-* headers from external requests before auth. Container not exposed to internet. |
+| Paperclip upstream changes auth middleware | Our `hosted_proxy` branch is isolated — rebase conflict is localized to one function |
+| User removed from platform but not from Paperclip | removeMember provision call is synchronous with platform removal. If it fails, retry with backoff. Future work: add periodic reconciliation job that compares platform org members with Paperclip company members and fixes drift. |
+| Company ID mapping lost | Store Paperclip companyId in tenant record during initial provisioning. Already returned by createTenant(). |
+
+## Future Considerations
+
+- **SSO/SAML:** Platform handles SSO, provisions users into Paperclip on first login via SAML callback
+- **Fine-grained permissions:** Platform roles (owner/admin/member) map to Paperclip roles. Could extend to map to Paperclip's `principalPermissionGrants` for granular control.
+- **Multi-instance orgs:** An org could have multiple Paperclip instances (staging/prod). Provisioning calls go to all instances.
+- **Audit trail:** Platform logs all membership changes. Paperclip logs activity via `onProvisioned` callback. Both sides have audit coverage.

package/docs/superpowers/specs/2026-03-14-role-permissions-design.md

@@ -0,0 +1,346 @@
+# Role Management & Permissions
+
+**Date:** 2026-03-14
+**Status:** Draft
+**Repos:** platform-core, platform-ui-core, paperclip, paperclip-platform, paperclip-platform-ui
+**Depends on:** `2026-03-14-paperclip-org-integration-design.md` (ships together or in strict sequence — this spec amends the org integration spec's `addMember`/`changeRole` to include permission grant provisioning)
+
+## Problem
+
+The platform has three org roles (owner/admin/member) that gate team management operations. But billing, fleet operations, update preferences, and Paperclip-internal permissions have no role gating. A member can see billing info, restart bots, create agents, and view costs — all of which should be admin-only.
+
+The platform controls the whole stack. Role enforcement happens at the right level: platform gates platform features, Paperclip gates Paperclip features. No workarounds.
+
+## Design
+
+### Permission Model
+
+Three fixed roles. No per-user customization. Simple, predictable, covers the product.
+
+**Owner** — full control. One per org.
+**Admin** — manages team, billing, fleet, agents. Cannot delete org or transfer ownership.
+**Member** — uses the product. Issues, projects, org chart. Nothing else.
+
+### Permission Matrix
+
+| Capability | Owner | Admin | Member |
+|---|---|---|---|
+| **Team** | | | |
+| Invite members | Y | Y | N |
+| Remove members | Y | Y | N |
+| Change roles | Y | Y | N |
+| Transfer ownership | Y | N | N |
+| Delete org | Y | N | N |
+| **Billing** | | | |
+| View balance/usage/invoices | Y | Y | N |
+| Top up credits | Y | Y | N |
+| **Fleet** | | | |
+| Start/stop/restart bot | Y | Y | N |
+| Trigger manual update | Y | Y | N |
+| Set update mode (auto/manual) | Y | Y | N |
+| View logs | Y | Y | Y |
+| View bot status/health | Y | Y | Y |
+| View changelog | Y | Y | Y |
+| **Inside Paperclip** | | | |
+| Create/manage agents | Y | Y | N |
+| View costs | Y | Y | N |
+| Delete company data | Y | N | N |
+| Create/edit issues | Y | Y | Y |
+| Create/edit projects | Y | Y | Y |
+| View org chart | Y | Y | Y |
+
+### Where Enforcement Happens
+
+Permissions are enforced at the correct layer — no double-gating, no workarounds.
+
+```
+Platform (tRPC routes)
+  ├─ Team management    → already gated by OrgService (owner/admin check on line 310)
+  ├─ Billing routes     → gate behind admin/owner role check
+  ├─ Fleet routes       → gate start/stop/restart/update behind admin/owner
+  └─ Fleet read routes  → allow all members (logs, status, health, changelog)
+
+Platform UI (platform-ui-core)
+  ├─ Settings tabs      → hide billing, fleet controls, team tabs for members
+  ├─ Update button      → hide for members (admin/owner only)
+  └─ Bot controls       → hide start/stop/restart for members
+
+Paperclip (provisioned permissions)
+  ├─ Agent management   → admin/owner get permission grants; members don't
+  ├─ Cost visibility    → admin/owner get cost view grants; members don't
+  ├─ Company deletion   → owner only gets delete grant
+  └─ Issues/projects    → all roles get full issue/project permissions
+```
+
+### 1. Platform-Side Role Gating (tRPC)
+
+**File:** `paperclip-platform/src/trpc/routers/fleet.ts`
+
+Fleet mutation routes (start, stop, restart, destroy, update) need admin/owner checks.
+
+**Prerequisite:** Today's `orgMemberProcedure` only checks membership existence — it does NOT check role or expose `member.role` to the context. A new `orgAdminProcedure` middleware is needed in platform-core:
+
+```typescript
+// platform-core: new middleware
+const orgAdminProcedure = protectedProcedure.use(async ({ ctx, next }) => {
+  const member = await orgMemberRepo.findMember(ctx.tenantId, ctx.user.id);
+  if (!member || member.role === "member") {
+    throw new TRPCError({ code: "FORBIDDEN", message: "Admin or owner role required" });
+  }
+  return next({ ctx: { ...ctx, orgRole: member.role } });
+});
+```
+
+Also extend `orgMemberProcedure` to attach `ctx.orgRole` so downstream code can read the role without re-querying.
+
+Fleet mutation routes switch from `protectedProcedure` to `orgAdminProcedure`. Fleet read routes (listInstances, getInstance, getInstanceHealth, getInstanceLogs) use `orgMemberProcedure` — accessible to all members.
+
+**File:** `paperclip-platform/src/trpc/routers/org.ts`
+
+Billing routes need admin/owner checks. The existing `requireAdminOrOwner` pattern at line 310 of `platform-core/src/tenancy/org-service.ts` should be extracted into a reusable helper:
+
+```typescript
+// platform-core/src/tenancy/org-service.ts
+async requireAdminOrOwner(orgId: string, userId: string): Promise<void> {
+  const member = await this.memberRepo.findMember(orgId, userId);
+  if (!member || (member.role !== "admin" && member.role !== "owner")) {
+    throw new TRPCError({ code: "FORBIDDEN", message: "Admin or owner role required" });
+  }
+}
+
+async requireOwner(orgId: string, userId: string): Promise<void> {
+  const org = await this.orgRepo.getOrg(orgId);
+  if (!org || org.ownerId !== userId) {
+    throw new TRPCError({ code: "FORBIDDEN", message: "Owner role required" });
+  }
+}
+```
+
+Apply to routes:
+
+| Route | Gate |
+|-------|------|
+| `orgBillingBalance` | `requireAdminOrOwner` |
+| `orgBillingInfo` | `requireAdminOrOwner` |
+| `orgMemberUsage` | `requireAdminOrOwner` |
+| `orgTopupCheckout` | `requireAdminOrOwner` |
+| `orgSetupIntent` | `requireAdminOrOwner` |
+| `inviteMember` | `requireAdminOrOwner` (already gated) |
+| `removeMember` | `requireAdminOrOwner` (already gated) |
+| `changeRole` | `requireAdminOrOwner` (already gated) |
+| `deleteOrganization` | `requireOwner` (already gated) |
+| `transferOwnership` | `requireOwner` (already gated) |
+
+### 2. Platform UI Role Gating
+
+**File:** `platform-ui-core/src/app/(dashboard)/settings/`
+
+The settings page needs to conditionally render tabs based on the user's role. The user's role is available from the org context (tRPC `getOrganization` response includes the member list with roles).
+
+```typescript
+// Hook: useMyOrgRole()
+// Returns "owner" | "admin" | "member" | null
+// Derived from org.members.find(m => m.userId === currentUser.id)?.role
+
+const role = useMyOrgRole();
+const isAdminOrOwner = role === "admin" || role === "owner";
+```
+
+**Tab visibility:**
+
+| Tab | Visible to |
+|-----|-----------|
+| Team / Members | admin, owner |
+| Billing | admin, owner |
+| Bot Management (start/stop/restart) | admin, owner |
+| Update Preferences | admin, owner |
+| Bot Status / Logs | all |
+| General Settings (name, etc.) | admin, owner |
+
+Members see a simplified dashboard: bot status, logs, changelog. No controls, no billing, no team management.
+
+**Update modal:**
+
+The "Update Available" badge and changelog are visible to all roles. The "Update Now" button is only visible to admin/owner. Members see the changelog but can't trigger the update.
+
+### 3. Paperclip-Side Permission Provisioning
+
+**File:** `paperclip/server/src/routes/provision.ts`
+
+When the platform provisions a user into Paperclip (via `addMember`), it also sets their permissions based on their platform role. This uses Paperclip's existing `principalPermissionGrants` system.
+
+**Permission grants by role:**
+
+Paperclip uses colon-delimited permission keys defined in `@paperclipai/shared/constants.ts`. The existing keys are: `agents:create`, `users:invite`, `users:manage_permissions`, `tasks:assign`, `tasks:assign_scope`, `joins:approve`.
+
+**Prerequisite:** Several permission keys needed for role-based gating do not exist yet. These must be added to `PERMISSION_KEYS` in `paperclip/packages/shared/src/constants.ts` before implementation:
+
+| New Key | Purpose |
+|---------|---------|
+| `agents:update` | Edit agent config |
+| `agents:delete` | Remove agents |
+| `costs:view` | See budget/spending |
+| `company:delete` | Delete entire company |
+
+```typescript
+import type { PermissionKey } from "@paperclipai/shared";
+
+type GrantInput = { permissionKey: PermissionKey; scope?: Record<string, unknown> | null };
+
+const ROLE_PERMISSIONS: Record<string, GrantInput[]> = {
+  owner: [
+    { permissionKey: "agents:create" },
+    { permissionKey: "agents:update" },
+    { permissionKey: "agents:delete" },
+    { permissionKey: "costs:view" },
+    { permissionKey: "company:delete" },
+    { permissionKey: "users:invite" },
+    { permissionKey: "users:manage_permissions" },
+    { permissionKey: "tasks:assign" },
+    { permissionKey: "joins:approve" },
+  ],
+  admin: [
+    { permissionKey: "agents:create" },
+    { permissionKey: "agents:update" },
+    { permissionKey: "agents:delete" },
+    { permissionKey: "costs:view" },
+    { permissionKey: "users:invite" },
+    { permissionKey: "users:manage_permissions" },
+    { permissionKey: "tasks:assign" },
+    { permissionKey: "joins:approve" },
+  ],
+  member: [
+    { permissionKey: "tasks:assign" },
+  ],
+};
+```
+
+**Note:** Issues and projects have no permission gates in Paperclip today — all company members can create/edit them. The org chart is also ungated — all authenticated users see it. No new keys needed for these.
+
+This spec **amends** the org integration spec's `addMember` and `changeRole` provision endpoints to include permission grant provisioning. Both changes ship together.
+
+The `addMember` provision endpoint sets these grants:
+
+```typescript
+async addMember(companyId: string, user: AdminUser, role: "owner" | "admin" | "member") {
+  await this.ensureUser(user);
+  const paperclipRole = role === "member" ? "member" : "owner";
+  await access.ensureMembership(companyId, "user", user.id, paperclipRole, "active");
+  if (paperclipRole === "owner") {
+    await access.promoteInstanceAdmin(user.id);
+  }
+
+  // Set permission grants based on platform role
+  const grants = ROLE_PERMISSIONS[role] ?? ROLE_PERMISSIONS.member;
+  await access.setPrincipalGrants(companyId, "user", user.id, grants, "platform");
+}
+```
+
+The `changeRole` endpoint updates grants when a role changes:
+
+```typescript
+async changeRole(companyId: string, userId: string, role: "owner" | "admin" | "member") {
+  // ... existing role/membership logic from org integration spec ...
+
+  // Update permission grants to match new role
+  const grants = ROLE_PERMISSIONS[role] ?? ROLE_PERMISSIONS.member;
+  await access.setPrincipalGrants(companyId, "user", userId, grants, "platform");
+}
+```
+
+### 4. Paperclip UI Enforcement (hostedMode)
+
+Paperclip's UI already has a permission system, but some controls need hostedMode-specific hiding. In hosted mode, the platform is the authority — Paperclip should not show controls that the platform's role doesn't allow.
+
+**Agent management controls:**
+Already gated by the `agent.create` permission grant. Members without the grant won't see create/edit/delete agent buttons. No additional hostedMode guard needed — the permission system handles it.
+
+**Cost page:**
+Gate behind `costs:view` permission. Members without it see a "Contact your admin" message or the page is hidden from navigation entirely.
+
+**Company deletion:**
+Already behind instance admin check. Members are never instance admin. No change needed.
+
+**Key principle:** In hosted mode, Paperclip's permission grants are the enforcement mechanism. The platform sets the right grants during provisioning. Paperclip's UI respects those grants. No additional hostedMode guards needed for role-based features — only for org management UI (invites, members, company settings) which is hidden entirely per the org integration spec.
+
+### 5. Role Change Propagation
+
+When a role changes on the platform, the change must propagate to Paperclip:
+
+```
+Platform: admin changes Alice from member to admin
+  → platform updates organization_members role
+  → platform calls POST instance:3100/internal/members/change-role
+    { companyId, userId: alice.id, role: "admin" }
+  → Paperclip updates membership + permission grants
+  → Alice's next request gets the expanded permissions
+```
+
+No restart needed. No container recreation. Permission grants take effect immediately on the next request because `actorMiddleware` resolves memberships fresh on each request.
+
+## Files to Create/Modify
+
+### platform-core
+
+| File | Action | Description |
+|------|--------|-------------|
+| `src/tenancy/org-service.ts` | Modify | Extract `requireAdminOrOwner()` and `requireOwner()` helpers |
+| `src/tenancy/org-member-procedure.ts` | Create | `orgAdminProcedure` middleware that checks admin/owner role; extend `orgMemberProcedure` to attach `ctx.orgRole` |
+
+### paperclip-platform
+
+| File | Action | Description |
+|------|--------|-------------|
+| `src/trpc/routers/fleet.ts` | Modify | Add admin/owner role checks to mutation routes |
+| `src/trpc/routers/org.ts` | Modify | Add admin/owner role checks to billing routes |
+
+### platform-ui-core
+
+| File | Action | Description |
+|------|--------|-------------|
+| `src/hooks/useMyOrgRole.ts` | Create | Hook to get current user's org role |
+| `src/app/(dashboard)/settings/` | Modify | Conditionally render tabs based on role |
+| Bot management components | Modify | Hide start/stop/restart controls for members |
+| Update modal | Modify | Hide "Update Now" button for members |
+
+### paperclip
+
+| File | Action | Description |
+|------|--------|-------------|
+| `server/src/routes/provision.ts` | Modify | Set permission grants based on platform role in addMember/changeRole |
+| `packages/shared/src/constants.ts` | Modify | Add new PERMISSION_KEYS: `agents:update`, `agents:delete`, `costs:view`, `company:delete` |
+
+### paperclip-platform-ui
+
+| File | Action | Description |
+|------|--------|-------------|
+| Settings layout | Modify | Hide billing/team/fleet tabs for members |
+| Bot card | Modify | Hide controls for members, keep status/logs visible |
+
+## Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| Owner demoted to member | Not possible — owner must transfer ownership first |
+| Last admin removed | OrgService already prevents this (countAdminsAndOwners check) |
+| Admin changes own role to member | Allowed — they lose admin access immediately |
+| User in multiple orgs with different roles | Roles are per-org. Switching org changes visible permissions |
+| Provision call fails during role change | Platform role is updated. Paperclip permissions are stale until retry succeeds. User may have expanded/restricted access temporarily. Reconciliation job (from org spec) catches drift. |
+| New permission added in future | Add to ROLE_PERMISSIONS map. Existing users get it on next role change or via reconciliation. |
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Platform and Paperclip permissions drift | Provision calls are synchronous with role changes. Reconciliation job as safety net. |
+| Upstream Paperclip adds new permission-gated features | Members won't have grants for new permissions by default — safe fail-closed. Admins get grants added via ROLE_PERMISSIONS update. |
+| Role check latency on every tRPC call | org member lookup is a single indexed query. Cache role in session if needed. |
+| Member sees flash of admin UI before role loads | `useMyOrgRole()` returns null while loading. Show skeleton/nothing until role resolves. |
+
+## Future Considerations
+
+- **Viewer role:** If a read-only role is needed (common enterprise request), add `"viewer"` to the role enum with an empty `ROLE_PERMISSIONS` entry. Viewers would see status/logs/changelog but cannot create issues or projects. The three-role model is extensible to four without architectural changes.
+- **Custom permission sets:** If customers need "billing admin" or "agent manager" sub-roles, extend ROLE_PERMISSIONS with custom role definitions. The infrastructure supports it — just add roles.
+- **Org-level feature flags:** Some features could be gated per org tier (enterprise gets more). Orthogonal to roles but shares the same gating infrastructure.
+- **Audit log:** Log all role changes and permission grant modifications for compliance.
+- **Reconciliation job:** Periodic job (e.g., hourly cron) that compares platform org members + roles against Paperclip company members + permission grants, and corrects any drift from failed provision calls. Defined in the org integration spec as future work — should be implemented alongside or shortly after initial ship.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/billing/crypto/evm/__tests__/config.test.ts

@@ -23,6 +23,18 @@ describe("getTokenConfig", () => {
     expect(cfg.contractAddress).toBe("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
   });
 
+  it("returns USDT on Base", () => {
+    const cfg = getTokenConfig("USDT", "base");
+    expect(cfg.decimals).toBe(6);
+    expect(cfg.contractAddress).toBe("0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2");
+  });
+
+  it("returns DAI on Base", () => {
+    const cfg = getTokenConfig("DAI", "base");
+    expect(cfg.decimals).toBe(18);
+    expect(cfg.contractAddress).toBe("0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb");
+  });
+
   it("throws on unsupported token/chain combo", () => {
     // biome-ignore lint/suspicious/noExplicitAny: testing invalid input
     expect(() => getTokenConfig("USDC" as any, "ethereum" as any)).toThrow("Unsupported token");

package/src/billing/crypto/evm/config.ts

@@ -10,13 +10,25 @@ const CHAINS: Record<EvmChain, ChainConfig> = {
   },
 };
 
-const TOKENS: Record<`${StablecoinToken}:${EvmChain}`, TokenConfig> = {
+const TOKENS: Partial<Record<`${StablecoinToken}:${EvmChain}`, TokenConfig>> = {
   "USDC:base": {
     token: "USDC",
     chain: "base",
     contractAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
     decimals: 6,
   },
+  "USDT:base": {
+    token: "USDT",
+    chain: "base",
+    contractAddress: "0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2",
+    decimals: 6,
+  },
+  "DAI:base": {
+    token: "DAI",
+    chain: "base",
+    contractAddress: "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
+    decimals: 18,
+  },
 };
 
 export function getChainConfig(chain: EvmChain): ChainConfig {

package/src/billing/crypto/evm/types.ts

@@ -2,7 +2,7 @@
 export type EvmChain = "base";
 
 /** Supported stablecoin tokens. */
-export type StablecoinToken = "USDC";
+export type StablecoinToken = "USDC" | "USDT" | "DAI";
 
 /** Chain configuration. */
 export interface ChainConfig {