@pymthouse/builder-sdk 0.4.4 → 0.4.6

package/README.md

@@ -70,20 +70,78 @@ For advanced flows that already have a user JWT, call
 
 ### Dashboard API keys (long-lived `pmth_*`)
 
-Create a key in the Dashboard **API keys** page, then exchange it for a signer
-session without repeating device login:
+Create a key in the Dashboard **API keys** page, then exchange it for a short-lived
+signer JWT without repeating device login. The facade mints credentials only;
+signing RPCs go **directly to the remote signer DMZ** returned as `signerUrl`.
+
+```ts
+import {
+  DIRECT_SIGNER_PATHS,
+  exchangeApiKeyForSigner,
+  signerEndpointUrl,
+} from "@pymthouse/builder-sdk/signer/server";
+
+const session = await exchangeApiKeyForSigner({
+  facadeUrl: process.env.DASHBOARD_ORIGIN!, // exchange only
+  apiKey: process.env.PMTH_API_KEY!,
+  scope: "sign:job",
+  clientId: process.env.PYMTHOUSE_PUBLIC_CLIENT_ID!,
+});
+
+const signerBase = session.signerUrl!; // remote signer DMZ from exchange
+const orchInfo = await fetch(
+  signerEndpointUrl(signerBase, DIRECT_SIGNER_PATHS.signOrchestratorInfo),
+  {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${session.access_token}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ /* ... */ }),
+  },
+);
+```
+
+Or via `PmtHouseClient` (returns `signerUrl` when using `facadeUrl`):
 
 ```ts
 const session = await client.exchangeApiKeyForSignerSession({
   apiKey: process.env.PMTH_API_KEY!,
-  facadeUrl: process.env.DASHBOARD_ORIGIN!, // e.g. https://dashboard.example.com
+  facadeUrl: process.env.DASHBOARD_ORIGIN!,
   scope: "sign:job",
 });
-// session.access_token — opaque signer bearer for discovery / gateway
+// session.access_token — short-lived signer JWT
+// session.signerUrl — remote signer DMZ base (call signer RPCs here directly)
 ```
 
 See `examples/stream-with-api-key.mjs` for a minimal Node script.
 
+### Exchange then direct signer (architecture)
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant Facade as PlatformFacade
+  participant Issuer as PymtHouseIssuer
+  participant Signer as RemoteSignerDMZ
+
+  Client->>Facade: POST /api/pymthouse/keys/exchange (pmth_*)
+  Facade->>Issuer: api-key token + M2M token exchange
+  Issuer-->>Facade: short-lived signer JWT + signerUrl
+  Facade-->>Client: access_token + signerUrl
+  Client->>Signer: POST {signerUrl}/sign-orchestrator-info (Bearer JWT)
+```
+
+**Do not** point `signerUrl` or gateway `--token signer` at dashboard
+`/api/signer/*` proxy routes. Those proxies are removed; use the remote signer
+DMZ URL from the exchange response (or `getSignerRouting().remoteDmzUrl`).
+
+**Migration:** if you previously configured
+`signer: https://dashboard.example.com/api/signer`, change to the remote signer
+base returned by exchange (`signerUrl`) or routing (`remoteDmzUrl`). Keep
+`facadeUrl` / `billing` pointed at the dashboard/platform origin for exchange
+only (`/api/pymthouse/keys/exchange` or `/api/signer/device/exchange`).
+
 Integrators can use the higher-level workflow helpers:
 
 ```ts
@@ -170,11 +228,64 @@ const customConfig = {
 Env vars align with `auth0-livepeer` bootstrap output (`.env.livepeer`). For Auth0,
 set `CLAIM_CLIENT_ID=azp` and `USAGE_SUBJECT_TYPE=auth0_user_id`.
 
+## Gateway `--token` helper
+
+The [livepeer-python-gateway](https://github.com/livepeer/livepeer-python-gateway)
+`--token` is a **base64-encoded JSON** bundle (not a JWT). `buildGatewayToken`
+assembles one client-side from values you already have, and `mintGatewayToken`
+mints a signer JWT first as a convenience.
+
+Two gateway auth modes:
+
+- **`signerJwt`** — you mint a signer JWT and forward it as
+  `signer_headers.Authorization = "Bearer <jwt>"`. The gateway only reads the
+  JWT `exp`; it cannot refresh on its own (pre-mint or refresh externally).
+- **`pmthApiKey`** — the gateway holds a `pmth_*` API key + the billing URL and
+  performs the exchange + auto-refresh itself (`api_key` + `billing` top-level).
+
+```ts
+import {
+  buildGatewayToken,
+  mintGatewayToken,
+} from "@pymthouse/builder-sdk/signer/gateway";
+
+// Pure assembly: pre-minted signer JWT mode
+const token = buildGatewayToken({
+  signer: "https://signer.example/generate-live-payment",
+  auth: { kind: "signerJwt", accessToken: userSignerJwt },
+});
+
+// Pure assembly: gateway self-refreshes via platform exchange, signs directly to signer
+const apiKeyToken = buildGatewayToken({
+  signer: "https://signer.example",
+  auth: {
+    kind: "pmthApiKey",
+    apiKey: process.env.PMTH_API_KEY!,
+    billing: "https://dashboard.example.com",
+  },
+});
+
+// Convenience: mint a signer JWT (M2M client_credentials) then assemble
+const minted = await mintGatewayToken({
+  source: "m2m",
+  signer: "https://signer.example/generate-live-payment",
+  issuerUrl: process.env.PYMTHOUSE_ISSUER_URL!,
+  m2mClientId: process.env.PYMTHOUSE_M2M_CLIENT_ID!,
+  m2mClientSecret: process.env.PYMTHOUSE_M2M_CLIENT_SECRET!,
+  externalUserId: "naap-user-123",
+});
+// Pass `token` straight to the gateway: `--token <token>`
+```
+
+Use `decodeGatewayToken(token)` to inspect a bundle in tests/debugging.
+
 ## Subpath exports
 
 | Import | Purpose |
 |--------|---------|
 | `@pymthouse/builder-sdk` | `PmtHouseClient`, usage helpers, manifest parsers, token helpers |
+| `@pymthouse/builder-sdk/signer/server` | Exchange handlers, direct signer URL helpers, minting, `buildGatewayToken`/`mintGatewayToken` |
+| `@pymthouse/builder-sdk/signer/gateway` | Gateway `--token` assembler (`buildGatewayToken`, `mintGatewayToken`, `decodeGatewayToken`) |
 | `@pymthouse/builder-sdk/signer/webhook` | Identity webhook for `-remoteSignerWebhookUrl` |
 | `@pymthouse/builder-sdk/config` | `isPymthouseConfigured`, `readPymthouseEnv` (Edge/middleware-safe) |
 | `@pymthouse/builder-sdk/tokens` | Signer session TTL, JWT shape helpers, `parseSignerSessionExchange` |
@@ -204,7 +315,11 @@ const summary = summarizeUsageForExternalUser(usage, externalUserId);
 
 **Retail estimates:** `getUsage({ includeRetail: true, groupBy: "pipeline_model" })` adds `endUserBillableUsdMicros` / fiat rows when the active plan has retail rates.
 
-**Metering:** sign directly against the remote signer DMZ with `createDirectSignerProxyHandler` or `forwardDirectSignerRequest`. Usage is emitted asynchronously by go-livepeer to Kafka and ingested by the OpenMeter collector. The PymtHouse `/api/signer/*` HTTP proxy and synchronous HTTP signed-ticket ingest are removed.
+**Metering:** after exchange, sign directly against the remote signer DMZ with
+`forwardToSigner`, `forwardDirectSignerRequest`, or plain `fetch` to
+`{signerUrl}/{path}`. Usage is emitted asynchronously by go-livepeer to Kafka
+and ingested by the OpenMeter collector. Dashboard `/api/signer/*` HTTP proxy
+routes and synchronous HTTP signed-ticket ingest are removed.
 
 **Routing:** `getSignerRouting()` returns the remote DMZ URL, webhook URL, and migration hints (`directDmz` / `deprecatedHostedFacade`).
 

package/dist/{client-C0HgAugK.d.cts → client-CEBVgCD7.d.cts}

@@ -1,5 +1,5 @@
 import { SignerSessionToken } from './tokens.cjs';
-import { P as PmtHouseClientOptions, G as GetDiscoveryOptions, O as OidcDiscoveryDocument, a as ParsedDeviceApprovalRedirect, A as AppUserRecord, U as UpsertAppUserInput, M as MintUserAccessTokenInput, b as MintUserAccessTokenResponse, T as TokenExchangeResponse, D as DeviceApprovalInput, C as ClientCredentialsTokenResponse, c as MintUserSignerSessionTokenInput, d as UsageQueryInput, e as UsageApiResponse, S as SignedTicketIngestInput, f as SignedTicketIngestResult, g as SignerRoutingResponse, L as ListBillingProductsResult, h as PlanSyncResult, i as UsageBalanceResponse, j as UserAllowancesResponse, k as UserAllowanceGrantInput, l as GrantSource, m as UserSubscriptionResponse, n as MeScopeUsagePayload, o as GetAppManifestResult, p as MintSignerSessionForExternalUserInput, q as ApproveDeviceLoginInput } from './types-BORaHW_x.cjs';
+import { P as PmtHouseClientOptions, G as GetDiscoveryOptions, O as OidcDiscoveryDocument, a as ParsedDeviceApprovalRedirect, A as AppUserRecord, U as UpsertAppUserInput, M as MintUserAccessTokenInput, b as MintUserAccessTokenResponse, T as TokenExchangeResponse, D as DeviceApprovalInput, C as ClientCredentialsTokenResponse, c as MintUserSignerSessionTokenInput, d as UsageQueryInput, e as UsageApiResponse, S as SignedTicketIngestInput, f as SignedTicketIngestResult, g as SignerRoutingResponse, L as ListBillingProductsResult, h as PlanSyncResult, i as UsageBalanceResponse, j as UserAllowancesResponse, k as UserAllowanceGrantInput, l as GrantSource, m as UserSubscriptionResponse, n as MeScopeUsagePayload, o as GetAppManifestResult, p as MintSignerSessionForExternalUserInput, q as ApproveDeviceLoginInput } from './types-CcP67AZm.cjs';
 
 /**
  * Normalize RFC 8628 user codes for comparison and resource URIs (uppercase, strip separators).
@@ -39,8 +39,14 @@ declare class PmtHouseClient {
         scope?: string;
     }): Promise<MintUserAccessTokenResponse>;
     /**
-     * Exchange a dashboard API key for a signer session via a trusted facade (recommended)
-     * or directly when M2M credentials are available on this client.
+     * Exchange a dashboard API key for a short-lived signer JWT via a trusted facade.
+     *
+     * `facadeUrl` is used only for `POST {facadeUrl}/api/pymthouse/keys/exchange`.
+     * After exchange, call signer RPCs directly at `signerUrl` from the response
+     * (e.g. `{signerUrl}/sign-orchestrator-info`), not via dashboard `/api/signer/*`.
+     *
+     * When M2M credentials are available on this client, omit `facadeUrl` to exchange
+     * directly against the PymtHouse issuer.
      */
     exchangeApiKeyForSignerSession(input: {
         apiKey: string;
@@ -52,6 +58,16 @@ declare class PmtHouseClient {
     exchangeForSignerSession(input: {
         userJwt: string;
         resource?: string;
+        /**
+         * When true, omit the RFC 8707 `resource` parameter entirely. This selects
+         * the documented PymtHouse gateway/opaque signer-session exchange
+         * (long-lived `pmth_*` token) rather than the signer-JWT path that a
+         * `resource = issuer` indicator routes to. Takes precedence over
+         * {@link resource}.
+         */
+        omitResource?: boolean;
+        /** Optional `scope` for the exchange (e.g. `sign:job`). Omitted when unset. */
+        scope?: string;
     }): Promise<TokenExchangeResponse>;
     /**
      * Mint a short-lived per-user JWT with the Builder API, then exchange it for
@@ -109,7 +125,15 @@ declare class PmtHouseClient {
         signal?: AbortSignal;
     }): Promise<GetAppManifestResult>;
     /**
-     * Upsert an external user, mint a short-lived JWT, and exchange for an opaque signer session.
+     * Upsert an external user, mint a short-lived JWT, and exchange it for a
+     * long-lived opaque (`pmth_*`) signer session.
+     *
+     * Performs the *documented* remote-signer-session exchange (see
+     * `builder-api.md` → "Remote signer session exchange"): the RFC 8693 token
+     * exchange is sent with `scope=sign:job` and **no `resource` indicator**,
+     * which selects the PymtHouse gateway/opaque path. A prior implementation set
+     * `resource = issuer`, which routed to the signer-JWT path and returned a JWT
+     * that {@link parseSignerSessionExchange} then rejected as non-opaque.
      */
     mintSignerSessionForExternalUser(input: MintSignerSessionForExternalUserInput): Promise<SignerSessionToken>;
     /**

package/dist/{client-zCskUJag.d.ts → client-D-p6v8ju.d.ts}

@@ -1,5 +1,5 @@
 import { SignerSessionToken } from './tokens.js';
-import { P as PmtHouseClientOptions, G as GetDiscoveryOptions, O as OidcDiscoveryDocument, a as ParsedDeviceApprovalRedirect, A as AppUserRecord, U as UpsertAppUserInput, M as MintUserAccessTokenInput, b as MintUserAccessTokenResponse, T as TokenExchangeResponse, D as DeviceApprovalInput, C as ClientCredentialsTokenResponse, c as MintUserSignerSessionTokenInput, d as UsageQueryInput, e as UsageApiResponse, S as SignedTicketIngestInput, f as SignedTicketIngestResult, g as SignerRoutingResponse, L as ListBillingProductsResult, h as PlanSyncResult, i as UsageBalanceResponse, j as UserAllowancesResponse, k as UserAllowanceGrantInput, l as GrantSource, m as UserSubscriptionResponse, n as MeScopeUsagePayload, o as GetAppManifestResult, p as MintSignerSessionForExternalUserInput, q as ApproveDeviceLoginInput } from './types-BORaHW_x.js';
+import { P as PmtHouseClientOptions, G as GetDiscoveryOptions, O as OidcDiscoveryDocument, a as ParsedDeviceApprovalRedirect, A as AppUserRecord, U as UpsertAppUserInput, M as MintUserAccessTokenInput, b as MintUserAccessTokenResponse, T as TokenExchangeResponse, D as DeviceApprovalInput, C as ClientCredentialsTokenResponse, c as MintUserSignerSessionTokenInput, d as UsageQueryInput, e as UsageApiResponse, S as SignedTicketIngestInput, f as SignedTicketIngestResult, g as SignerRoutingResponse, L as ListBillingProductsResult, h as PlanSyncResult, i as UsageBalanceResponse, j as UserAllowancesResponse, k as UserAllowanceGrantInput, l as GrantSource, m as UserSubscriptionResponse, n as MeScopeUsagePayload, o as GetAppManifestResult, p as MintSignerSessionForExternalUserInput, q as ApproveDeviceLoginInput } from './types-CcP67AZm.js';
 
 /**
  * Normalize RFC 8628 user codes for comparison and resource URIs (uppercase, strip separators).
@@ -39,8 +39,14 @@ declare class PmtHouseClient {
         scope?: string;
     }): Promise<MintUserAccessTokenResponse>;
     /**
-     * Exchange a dashboard API key for a signer session via a trusted facade (recommended)
-     * or directly when M2M credentials are available on this client.
+     * Exchange a dashboard API key for a short-lived signer JWT via a trusted facade.
+     *
+     * `facadeUrl` is used only for `POST {facadeUrl}/api/pymthouse/keys/exchange`.
+     * After exchange, call signer RPCs directly at `signerUrl` from the response
+     * (e.g. `{signerUrl}/sign-orchestrator-info`), not via dashboard `/api/signer/*`.
+     *
+     * When M2M credentials are available on this client, omit `facadeUrl` to exchange
+     * directly against the PymtHouse issuer.
      */
     exchangeApiKeyForSignerSession(input: {
         apiKey: string;
@@ -52,6 +58,16 @@ declare class PmtHouseClient {
     exchangeForSignerSession(input: {
         userJwt: string;
         resource?: string;
+        /**
+         * When true, omit the RFC 8707 `resource` parameter entirely. This selects
+         * the documented PymtHouse gateway/opaque signer-session exchange
+         * (long-lived `pmth_*` token) rather than the signer-JWT path that a
+         * `resource = issuer` indicator routes to. Takes precedence over
+         * {@link resource}.
+         */
+        omitResource?: boolean;
+        /** Optional `scope` for the exchange (e.g. `sign:job`). Omitted when unset. */
+        scope?: string;
     }): Promise<TokenExchangeResponse>;
     /**
      * Mint a short-lived per-user JWT with the Builder API, then exchange it for
@@ -109,7 +125,15 @@ declare class PmtHouseClient {
         signal?: AbortSignal;
     }): Promise<GetAppManifestResult>;
     /**
-     * Upsert an external user, mint a short-lived JWT, and exchange for an opaque signer session.
+     * Upsert an external user, mint a short-lived JWT, and exchange it for a
+     * long-lived opaque (`pmth_*`) signer session.
+     *
+     * Performs the *documented* remote-signer-session exchange (see
+     * `builder-api.md` → "Remote signer session exchange"): the RFC 8693 token
+     * exchange is sent with `scope=sign:job` and **no `resource` indicator**,
+     * which selects the PymtHouse gateway/opaque path. A prior implementation set
+     * `resource = issuer`, which routed to the signer-JWT path and returned a JWT
+     * that {@link parseSignerSessionExchange} then rejected as non-opaque.
      */
     mintSignerSessionForExternalUser(input: MintSignerSessionForExternalUserInput): Promise<SignerSessionToken>;
     /**

package/dist/device.d.cts

@@ -1,5 +1,5 @@
 import * as oauth4webapi from 'oauth4webapi';
-import { F as FetchLike } from './types-BORaHW_x.cjs';
+import { F as FetchLike } from './types-CcP67AZm.cjs';
 
 interface PollDeviceTokenOptions {
     issuerUrl: string;

package/dist/device.d.ts

@@ -1,5 +1,5 @@
 import * as oauth4webapi from 'oauth4webapi';
-import { F as FetchLike } from './types-BORaHW_x.js';
+import { F as FetchLike } from './types-CcP67AZm.js';
 
 interface PollDeviceTokenOptions {
     issuerUrl: string;

package/dist/env.cjs

@@ -307,6 +307,32 @@ var init_mint_token = __esm({
   }
 });
 
+// src/signer/direct-signer.ts
+function assertDirectSignerBaseUrl(signerBaseUrl) {
+  let parsed;
+  try {
+    parsed = new URL(signerBaseUrl.trim());
+  } catch {
+    throw new PmtHouseError("signer URL must be an absolute http(s) URL", {
+      status: 400,
+      code: "invalid_signer_url"
+    });
+  }
+  const pathname = stripTrailingSlashes(parsed.pathname);
+  if (pathname === "/api/signer" || pathname.startsWith("/api/signer/")) {
+    throw new PmtHouseError(
+      "signer URL must be the remote signer DMZ base, not a dashboard /api/signer/* proxy path. Exchange at the platform facade, then call signer endpoints directly using signerUrl from the exchange response.",
+      { status: 400, code: "invalid_signer_url" }
+    );
+  }
+}
+var init_direct_signer = __esm({
+  "src/signer/direct-signer.ts"() {
+    init_string_utils();
+    init_errors();
+  }
+});
+
 // src/signer/device-exchange.ts
 function extractSignerAccessTokenFromExchangeBody(body) {
   const tokenObj = body.token;
@@ -539,6 +565,9 @@ async function exchangeApiKeyForSigner(options) {
   const accessToken = extractSignerAccessTokenFromExchangeBody(parsed);
   const signerUrlRaw = parsed.signerUrl ?? parsed.signer_url;
   const signerUrl = typeof signerUrlRaw === "string" && signerUrlRaw.trim() ? signerUrlRaw.trim() : void 0;
+  if (signerUrl) {
+    assertDirectSignerBaseUrl(signerUrl);
+  }
   return normalizeDeviceExchangeResponse(
     {
       access_token: accessToken,
@@ -601,6 +630,7 @@ var init_api_key_exchange = __esm({
     init_fetch_json();
     init_handler_errors();
     init_device_exchange();
+    init_direct_signer();
     EXCHANGE_RESPONSE_ERROR2 = "invalid_exchange_response";
   }
 });
@@ -1097,8 +1127,14 @@ var PmtHouseClient = class {
     });
   }
   /**
-   * Exchange a dashboard API key for a signer session via a trusted facade (recommended)
-   * or directly when M2M credentials are available on this client.
+   * Exchange a dashboard API key for a short-lived signer JWT via a trusted facade.
+   *
+   * `facadeUrl` is used only for `POST {facadeUrl}/api/pymthouse/keys/exchange`.
+   * After exchange, call signer RPCs directly at `signerUrl` from the response
+   * (e.g. `{signerUrl}/sign-orchestrator-info`), not via dashboard `/api/signer/*`.
+   *
+   * When M2M credentials are available on this client, omit `facadeUrl` to exchange
+   * directly against the PymtHouse issuer.
    */
   async exchangeApiKeyForSignerSession(input) {
     if (input.facadeUrl?.trim()) {
@@ -1115,7 +1151,8 @@ var PmtHouseClient = class {
         token_type: exchanged.token_type,
         expires_in: exchanged.expires_in,
         scope: exchanged.scope,
-        issued_token_type: "urn:ietf:params:oauth:token-type:access_token"
+        issued_token_type: "urn:ietf:params:oauth:token-type:access_token",
+        signerUrl: exchanged.signerUrl
       };
     }
     const userToken = await this.exchangeApiKeyForUserAccessToken({
@@ -1189,8 +1226,13 @@ var PmtHouseClient = class {
     params.set("subject_token", input.userJwt);
     params.set("subject_token_type", SUBJECT_ACCESS_TOKEN_TYPE2);
     params.set("requested_token_type", REQUESTED_ACCESS_TOKEN_TYPE);
-    const resourceCandidate = typeof input.resource === "string" && input.resource.trim() !== "" ? input.resource.trim() : this.issuerUrl;
-    params.set("resource", stripTrailingSlashes(resourceCandidate));
+    if (typeof input.scope === "string" && input.scope.trim() !== "") {
+      params.set("scope", input.scope.trim());
+    }
+    if (!input.omitResource) {
+      const resourceCandidate = typeof input.resource === "string" && input.resource.trim() !== "" ? input.resource.trim() : this.issuerUrl;
+      params.set("resource", stripTrailingSlashes(resourceCandidate));
+    }
     try {
       const response = await oauth4webapi.genericTokenEndpointRequest(
         as,
@@ -1476,18 +1518,31 @@ var PmtHouseClient = class {
     };
   }
   /**
-   * Upsert an external user, mint a short-lived JWT, and exchange for an opaque signer session.
+   * Upsert an external user, mint a short-lived JWT, and exchange it for a
+   * long-lived opaque (`pmth_*`) signer session.
+   *
+   * Performs the *documented* remote-signer-session exchange (see
+   * `builder-api.md` → "Remote signer session exchange"): the RFC 8693 token
+   * exchange is sent with `scope=sign:job` and **no `resource` indicator**,
+   * which selects the PymtHouse gateway/opaque path. A prior implementation set
+   * `resource = issuer`, which routed to the signer-JWT path and returned a JWT
+   * that {@link parseSignerSessionExchange} then rejected as non-opaque.
    */
   async mintSignerSessionForExternalUser(input) {
+    const scope = input.scope ?? SIGN_JOB_SCOPE;
     await this.upsertAppUser({
       externalUserId: input.externalUserId,
       email: input.email,
       status: "active"
     });
-    const exchange = await this.mintUserSignerSessionToken({
+    const userToken = await this.mintUserAccessToken({
       externalUserId: input.externalUserId,
-      scope: input.scope ?? SIGN_JOB_SCOPE,
-      resource: this.issuerUrl
+      scope
+    });
+    const exchange = await this.exchangeForSignerSession({
+      userJwt: userToken.access_token,
+      omitResource: true,
+      scope
     });
     return parseSignerSessionExchange(exchange);
   }