@tangle-network/agent-app 0.3.1 → 0.5.0

package/dist/platform/index.d.ts

@@ -0,0 +1,339 @@
+import { PlatformIdentity, PlatformBillingClient } from '../billing/index.js';
+
+/**
+ * Cross-site Tangle SSO for agent apps: signed-state CSRF cookies plus the
+ * full start/callback orchestration against the platform's /cross-site
+ * bridge. The platform wire client and account persistence are structural
+ * seams (`TangleSsoAuthClient` / `TangleSsoAccountStore`), so this module
+ * never imports agent-runtime, an auth framework, or a database driver.
+ * WebCrypto only — runs in workerd without node compatibility flags.
+ */
+interface SsoStateConfig {
+    /** HMAC-SHA256 secret (e.g. the app's auth secret). */
+    secret: string;
+    /** State lifetime in ms. Default 600 000. */
+    ttlMs?: number;
+    /** Injectable clock (ms since epoch). Default Date.now. */
+    now?: () => number;
+}
+/** Mint a `<randomHex32>.<timestamp36>.<hmacHex>` state value. The timestamp
+ *  is inside the signed payload, so expiry survives cookie-attribute tampering. */
+declare function createSignedSsoState(config: SsoStateConfig): Promise<string>;
+/** Verify the MAC (constant-time) and the signed TTL. */
+declare function verifySignedSsoState(state: string, config: SsoStateConfig): Promise<boolean>;
+interface TangleSsoExchangeResult {
+    apiKey: string;
+    user: {
+        id: string;
+        email: string;
+        name?: string | null;
+    };
+    plan?: {
+        tier: string;
+    } | null;
+}
+/** Structural mirror of the platform auth wire client — any object with these
+ *  two methods satisfies it without this module importing the concrete class. */
+interface TangleSsoAuthClient {
+    authorizeUrl(options: {
+        state: string;
+        redirectUri?: string;
+    }): string;
+    exchange(code: string): Promise<TangleSsoExchangeResult>;
+}
+/** Thrown by `upsertUserByEmail` when the app-local user row cannot be
+ *  created; the callback handler maps it to `?error=tangle_user_create_failed`.
+ *  Any other store error propagates. */
+declare class TangleSsoUserCreateError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Account persistence seam. Covers both storage styles in use: link-table
+ * apps (a per-user platform-link row) and session-column apps (the key on the
+ * session row) — `saveTangleLink` receives both `userId` and `sessionToken`,
+ * and each app persists with the key it needs. `createSession` runs first so
+ * the token is always available to `saveTangleLink`.
+ */
+interface TangleSsoAccountStore {
+    /** Find-or-create the app-local user for the platform email. */
+    upsertUserByEmail(input: {
+        email: string;
+        name: string | null;
+    }): Promise<{
+        userId: string;
+    }>;
+    /** Create an app session row; returns the session-cookie token value. */
+    createSession(input: {
+        userId: string;
+        expiresAt: Date;
+        ipAddress: string | null;
+        userAgent: string | null;
+    }): Promise<{
+        token: string;
+    }>;
+    /** Persist the platform link (API key + platform identity). */
+    saveTangleLink(input: {
+        userId: string;
+        sessionToken: string;
+        tangleUserId: string;
+        email: string;
+        name: string | null;
+        apiKey: string;
+        planTier: string | null;
+    }): Promise<void>;
+}
+interface TangleSsoHandlerOptions {
+    auth: TangleSsoAuthClient;
+    store: TangleSsoAccountStore;
+    /** HMAC secret for the state cookie. */
+    stateSecret: string;
+    /** Absolute callback URL registered with the platform. */
+    callbackUrl: string;
+    stateCookieName: string;
+    /** Default 'better-auth.session_token'. */
+    sessionCookieName?: string;
+    /** Adds `Secure` to every cookie this module sets. */
+    secureCookies: boolean;
+    /** Default 604 800 (7 days). */
+    sessionTtlSeconds?: number;
+    /** Default 600. Applies to both the cookie Max-Age and the signed TTL. */
+    stateTtlSeconds?: number;
+    /** Default '/app'. */
+    defaultRedirectPath?: string;
+    /** Default '/login'. */
+    loginPath?: string;
+    /** Failure log hook (e.g. console.error). Default no-op. */
+    log?: (message: string, error?: unknown) => void;
+    now?: () => number;
+}
+interface TangleSsoHandlers {
+    /** GET start route: mint + sign state, set the state cookie, 302 to the
+     *  platform authorize URL. `?redirect=` carries the post-login path. */
+    start(request: Request): Promise<Response>;
+    /** GET callback route: verify state, exchange the code, upsert the user,
+     *  create the session, save the platform link, set the session cookie,
+     *  302 to the saved redirect. Every failure 302s to
+     *  `loginPath?error=…` with the state cookie cleared. */
+    callback(request: Request): Promise<Response>;
+}
+declare function createTangleSsoHandlers(opts: TangleSsoHandlerOptions): TangleSsoHandlers;
+
+/**
+ * Integrations-hub proxy routes: the app-side surface that forwards an
+ * authenticated user's requests to the platform's `/v1/integrations/*` API
+ * using their stored platform key. Auth, key lookup, and the wire client are
+ * structural seams (`HubProxyContext`); error detection is by name + shape so
+ * it survives bundlers duplicating module instances.
+ */
+declare class TangleBearerMissingError extends Error {
+    readonly userId: string;
+    constructor(userId: string);
+}
+/** Structural guard (name + userId shape) — robust when the error class is
+ *  constructed in a different module instance than the one checking it. */
+declare function isTangleBearerMissingError(error: unknown): error is TangleBearerMissingError;
+/** Structural detection of the platform hub wire error (name + numeric status). */
+declare function isPlatformHubErrorLike(error: unknown): error is Error & {
+    status: number;
+    code?: string;
+};
+/** Structural subset of the platform hub wire client — extra methods are fine. */
+interface HubClientLike {
+    catalog(): Promise<unknown>;
+    listConnections(): Promise<unknown>;
+    revokeConnection(connectionId: string): Promise<unknown>;
+    startAuth(input: {
+        providerId: string;
+        connectorId: string;
+        returnUrl: string;
+        requestedScopes?: string[];
+    }): Promise<{
+        authorizationUrl: string;
+        state: string;
+    }>;
+    listHealthchecks(): Promise<unknown>;
+}
+interface HubProxyContext {
+    /** Resolve the authenticated user id. Throw the app's own auth Response /
+     *  redirect to reject — it propagates untouched. */
+    requireUserId(request: Request): Promise<string>;
+    /** The user's platform bearer; throw `TangleBearerMissingError` when unlinked. */
+    getBearer(userId: string): Promise<string>;
+    /** A hub client bound to the bearer. */
+    createHubClient(bearer: string): HubClientLike;
+}
+interface HubProxyRouteArgs {
+    request: Request;
+    params?: Record<string, string | undefined>;
+}
+interface HubProxyRoutes {
+    /** GET → `{ catalog }`. */
+    catalog(args: HubProxyRouteArgs): Promise<Response>;
+    /** GET → `{ connections }`. */
+    connections(args: HubProxyRouteArgs): Promise<Response>;
+    /** DELETE → the platform revocation result verbatim; 405 otherwise. */
+    connectionDelete(args: {
+        request: Request;
+        params: {
+            connectionId: string;
+        };
+    }): Promise<Response>;
+    /** GET → `{ healthchecks }`. */
+    healthchecks(args: HubProxyRouteArgs): Promise<Response>;
+    /** POST `{ providerId, connectorId, returnUrl, requestedScopes? }` →
+     *  `{ authorizationUrl, state }`; 405 non-POST; 400 on bad JSON / missing fields. */
+    authStart(args: HubProxyRouteArgs): Promise<Response>;
+}
+declare function createHubProxyRoutes(ctx: HubProxyContext): HubProxyRoutes;
+
+/**
+ * Platform billing HTTP transport + tier state for apps on the shared
+ * Tangle balance model (id.tangle.tools). Reads authenticate as the user via
+ * their per-user platform key (the platform resolves the caller from the
+ * key; service or impersonation headers on read routes are rejected). The
+ * deduct write authenticates as the product service (`Bearer <serviceToken>`
+ * + `X-Service-Name`) and names the target user in the body. Also provides a
+ * fetch-backed implementation of the `/billing` module's
+ * `PlatformBillingClient` seam (type-only import — no runtime coupling).
+ */
+
+type TanglePlanTier = 'free' | 'pro' | 'enterprise';
+/** 'pro' | 'enterprise' pass through; anything else (null, unknown) → 'free'. */
+declare function normalizeTanglePlanTier(plan: string | null | undefined): TanglePlanTier;
+declare class PlatformBillingHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, detail: string);
+}
+/** Structural guard (name + numeric status) — robust across module instances. */
+declare function isPlatformBillingHttpError(error: unknown): error is PlatformBillingHttpError;
+interface PlatformBillingHttpOptions {
+    /** Platform root, e.g. https://id.tangle.tools (trailing slashes stripped). */
+    baseUrl: string;
+    /** Used only by `deduct()`; resolved lazily so reads never require it.
+     *  Throws at call time when empty. */
+    serviceToken: string | (() => string);
+    /** Product slug — the `X-Service-Name` header and the deduct `product` field. */
+    productSlug: string;
+    fetchImpl?: typeof fetch;
+    /** Default 10 000. */
+    timeoutMs?: number;
+}
+interface PlatformSubscriptionInfo {
+    tier: TanglePlanTier;
+    status: string | null;
+}
+interface PlatformBalanceSnapshot {
+    balance: number;
+    lifetimeSpent: number;
+    updatedAt?: string;
+}
+interface PlatformUsageProductRow {
+    product: string | null;
+    totalSpent: number;
+    count: number;
+}
+interface PlatformBillingHttp {
+    /** GET /v1/plans/current (user bearer). */
+    getSubscription(userApiKey: string): Promise<PlatformSubscriptionInfo>;
+    /** GET /v1/billing/balance (user bearer). */
+    getBalance(userApiKey: string): Promise<PlatformBalanceSnapshot>;
+    /** GET /v1/billing/usage (user bearer). */
+    getUsageByProduct(userApiKey: string): Promise<PlatformUsageProductRow[]>;
+    /** POST /v1/billing/deduct (service token). */
+    deduct(input: {
+        platformUserId: string;
+        amountUsd: number;
+        type: string;
+        description: string;
+        referenceId: string;
+    }): Promise<void>;
+    /** Absolute URL of the platform's billing-management surface. */
+    billingUrl(): string;
+}
+declare function createPlatformBillingHttp(opts: PlatformBillingHttpOptions): PlatformBillingHttp;
+interface TangleTierPolicy {
+    concurrency: number;
+    overageAllowed: boolean;
+}
+declare const DEFAULT_TANGLE_TIER_POLICY: Record<TanglePlanTier, TangleTierPolicy>;
+interface TangleTierState {
+    tier: TanglePlanTier;
+    subscriptionStatus: string | null;
+    remainingBalanceUsd: number;
+    lifetimeSpentUsd: number;
+    concurrency: number;
+    overageAllowed: boolean;
+}
+/**
+ * Read subscription + balance and project them onto the tier policy. A
+ * null/absent key fails CLOSED (free tier, zero balance) — a billable run is
+ * never started against an unknown balance. Platform errors throw; callers
+ * on the billable path choose their posture explicitly.
+ */
+declare function readTangleTierState(http: PlatformBillingHttp, userApiKey: string | null | undefined, policy?: Record<TanglePlanTier, TangleTierPolicy>): Promise<TangleTierState>;
+interface PlatformIdentityStore {
+    resolveIdentity(userId: string): Promise<PlatformIdentity | null>;
+}
+/** Concrete fetch-backed `PlatformBillingClient<TanglePlanTier>` for
+ *  `createPlatformBalanceManager` (from `/billing`). */
+declare function createTanglePlatformBillingClient(http: PlatformBillingHttp, identity: PlatformIdentityStore): PlatformBillingClient<TanglePlanTier>;
+
+/**
+ * Request guards for agent-app routes: session auth (302 redirect for pages,
+ * JSON 401 for APIs), admin allowlisting (404 — the route stays invisible to
+ * non-admins), and the billable-balance gate (402 with a stable code).
+ * Session resolution is a seam; thrown Responses follow the router convention
+ * of surfacing a thrown Response as the route result.
+ */
+interface AuthGuardOptions<Session> {
+    /** e.g. a better-auth `auth.api.getSession` wrapped by the app. */
+    getSession(request: Request): Promise<Session | null | undefined>;
+    /** Default '/login'. */
+    loginPath?: string;
+}
+interface AuthGuard<Session> {
+    /** Page guard — throws a 302 redirect Response to `loginPath`. */
+    requireUser(request: Request): Promise<Session>;
+    /** API guard — throws JSON 401 `{ error: 'Unauthorized', code: 'auth.unauthenticated' }`. */
+    requireApiUser(request: Request): Promise<Session>;
+    /** `apiResponse` selects the 401 JSON path over the redirect. */
+    requireSession(request: Request, opts?: {
+        apiResponse?: boolean;
+    }): Promise<Session>;
+    getOptionalSession(request: Request): Promise<Session | null>;
+}
+declare function createAuthGuard<Session>(opts: AuthGuardOptions<Session>): AuthGuard<Session>;
+/** Comma/whitespace separated → trimmed, lowercased, empties dropped. */
+declare function parseAdminEmails(raw: string | null | undefined): string[];
+interface AdminGuardOptions<Session> {
+    requireUser(request: Request): Promise<Session>;
+    emailOf(session: Session): string | null | undefined;
+    /** Resolved per request; an EMPTY allowlist refuses everyone. */
+    allowedEmails(): string[];
+}
+/** Non-admins (and empty allowlists) get 404, keeping the route invisible —
+ *  better than a "forbidden" footprint that advertises its existence. */
+declare function createAdminGuard<Session>(opts: AdminGuardOptions<Session>): (request: Request) => Promise<Session>;
+interface BillableBalanceState {
+    overageAllowed: boolean;
+    remainingBalanceUsd: number;
+}
+interface AssertBillableBalanceOptions {
+    env?: Record<string, string | undefined>;
+    /** App-specific enforcement override flag (e.g. 'GTM_BILLING_ENFORCEMENT'),
+     *  fed to `isTangleBillingEnforcementDisabled`. */
+    enforcementEnvVar?: string;
+    /** Default 'Add balance or upgrade your plan to invoke this agent.'. */
+    errorMessage?: string;
+    /** Merged into the 402 JSON body (e.g. `{ organizationId }`). */
+    errorBody?: Record<string, unknown>;
+}
+/**
+ * Gate a billable turn: passes when enforcement is disabled (dev default),
+ * the tier allows overage, or remaining balance is positive. Otherwise throws
+ * a 402 Response with the stable `billing.balance_required` code so clients
+ * can route to the billing screen.
+ */
+declare function assertBillableBalance(state: BillableBalanceState, opts?: AssertBillableBalanceOptions): void;
+
+export { type AdminGuardOptions, type AssertBillableBalanceOptions, type AuthGuard, type AuthGuardOptions, type BillableBalanceState, DEFAULT_TANGLE_TIER_POLICY, type HubClientLike, type HubProxyContext, type HubProxyRouteArgs, type HubProxyRoutes, type PlatformBalanceSnapshot, type PlatformBillingHttp, PlatformBillingHttpError, type PlatformBillingHttpOptions, type PlatformIdentityStore, type PlatformSubscriptionInfo, type PlatformUsageProductRow, type SsoStateConfig, TangleBearerMissingError, type TanglePlanTier, type TangleSsoAccountStore, type TangleSsoAuthClient, type TangleSsoExchangeResult, type TangleSsoHandlerOptions, type TangleSsoHandlers, TangleSsoUserCreateError, type TangleTierPolicy, type TangleTierState, assertBillableBalance, createAdminGuard, createAuthGuard, createHubProxyRoutes, createPlatformBillingHttp, createSignedSsoState, createTanglePlatformBillingClient, createTangleSsoHandlers, isPlatformBillingHttpError, isPlatformHubErrorLike, isTangleBearerMissingError, normalizeTanglePlanTier, parseAdminEmails, readTangleTierState, verifySignedSsoState };