6.nOAuth abstraction in the Console: providers as data, connections per user

1. Why OAuth is a foundation concern

Every PayCargo cartridge that integrates a SaaS system of record (Salesforce, GitHub, GitBook, Monday) will need OAuth. If each cartridge implements its own OAuth flow, four things go wrong:

• Drift. Two cartridges accept slightly different state-parameter formats. One forgets PKCE. One stores tokens in DDB instead of Secrets Manager. Within three cartridges, "how we handle Salesforce auth" has three different shapes.
• Surface area. Salesforce credentials touch every cartridge folder. Rotating the Connected App client_secret means PRs against N cartridges instead of one.
• Refresh chaos. Each cartridge implements its own refresh logic. Two cartridges hit the expiry boundary simultaneously, both refresh, one of them loses the race, Salesforce rate-limits the connected app.
• Audit holes. No single answer to "who connected Salesforce" or "which user's token was used at 14:32:01."

The Forge model already says cartridges declare; the platform enforces. OAuth is the same pattern. The Console owns the OAuth flow. Cartridges declare which providers they consume, and the foundation hands them a current valid token.

2. Three concepts: provider, connection, consumer

Distinct on purpose. Mixing them is the root cause of every OAuth abstraction that ages badly.

Adding a provider is one SSM parameter. Adding a connection is one OAuth flow run by an end user. Adding a consumer is zero work for the OAuth layer; the cartridge calls getOAuthConnection('salesforce-sandbox') and it just works.

3. Connections are per-user (and why per-cartridge is a trap)

The platform-shared option, briefly

Tempting first instinct: one "PayCargo Salesforce connection" the whole platform shares. Wrong, because every Salesforce API call would look like it came from a single service account, defeating Salesforce's audit log on our side. The Salesforce admins would have one row for everything. Compliance fails.

The per-cartridge option is worse

If every cartridge has its own Salesforce connection, every cartridge has its own login flow, its own refresh token, its own Connected App. The auth surface multiplies with N cartridges. Operators connect Salesforce five times, once per cartridge, with five sets of consent screens. Every cartridge's IAM role needs Salesforce client secret read access. The refresh scheduler iterates N times more.

And the operational insight that closes the case: we cannot escape a role boundary anyway. IAM permission boundaries already constrain what each cartridge's role can do. Layering an application-level "this connection is only for cartridge X" check on top of an IAM boundary that already enforces "this role can only do Y" is redundant complexity with no marginal safety. The role boundary is the trap door; application-level scoping is theater.

The per-user model that works

One connection per user per provider. mtang connects Salesforce Sandbox once in Setup. Every cartridge invocation made by mtang resolves getOAuthConnection('salesforce-sandbox') to mtang's token. jdoe needs to connect separately to make Salesforce calls under her own identity. Salesforce's audit log shows the right user every time.

4. Provider registry: data in SSM, not code

A provider is a JSON manifest under /forge/oauth/providers/<provider_id> in SSM Parameter Store. Adding a provider means adding a Terraform aws_ssm_parameter resource. The OAuth flow Lambda reads the registry at runtime, never hard-codes provider URLs.

Example: Salesforce Sandbox manifest

{
  "id":                  "salesforce-sandbox",
  "display_name":        "Salesforce Sandbox",
  "icon":                "fa-solid fa-cloud-arrow-up",
  "authorize_url":       "https://test.salesforce.com/services/oauth2/authorize",
  "token_url":           "https://test.salesforce.com/services/oauth2/token",
  "revoke_url":          "https://test.salesforce.com/services/oauth2/revoke",
  "userinfo_url":        "https://test.salesforce.com/services/oauth2/userinfo",
  "scopes_requested":    ["api", "refresh_token", "offline_access"],
  "use_pkce":            true,
  "callback_url":        "https://console.paycargo.org/api/oauth/callback/salesforce-sandbox",
  "client_id_secret_arn": "arn:aws:secretsmanager:us-east-1:959228203854:secret:/forge/oauth/clients/salesforce-sandbox",
  "metadata_fields":     ["instance_url", "id"],
  "refresh_window_min":  60,
  "adapter":             "salesforce",
  "capabilities": [
    { "name": "soql",           "scope_required": "api", "summary": "Run a SOQL query, returns records" },
    { "name": "sobject.get",    "scope_required": "api", "summary": "Read one sobject by id" },
    { "name": "sobject.create", "scope_required": "api", "summary": "Create one sobject" },
    { "name": "sobject.update", "scope_required": "api", "summary": "Update one sobject by id" },
    { "name": "sobject.delete", "scope_required": "api", "summary": "Delete one sobject by id" },
    { "name": "describe",       "scope_required": "api", "summary": "Get sobject metadata" },
    { "name": "bulk.query",     "scope_required": "api", "summary": "Bulk API SOQL for large result sets" }
  ]
}

metadata_fields is the abstraction's escape hatch for provider-specific response fields. Salesforce returns instance_url in the token response; this manifest tells the OAuth flow to persist it as connection metadata. GitHub's token response has no instance URL; GitHub's manifest omits the field. No code change.

refresh_window_min: 60 tells the scheduler to refresh anything expiring in the next 60 minutes. Per-provider tunable.

adapter names which file in shared/modules/oauth/adapters/ implements this provider's capability surface. capabilities is the data-side declaration of what the adapter exposes. See section 6 below for what these do.

Provider catalog (v1 and roadmap)

The egress allowlist (Step 3) already lets these five domains out of the VPC. OAuth is the layer above that enforcement.

5. The Setup tab

New top-level tab in the Console app. Available to every authenticated user (not admin-gated): each user manages their own connections.

Layout

Status semantics

Actions per connection

• Re-authenticate: kicks off a fresh OAuth flow, reuses the connection slot, refresh token rotated.
• Disconnect: calls the provider's revoke endpoint, deletes the Secrets Manager entry, deletes the DDB row.
• View activity: opens the obs Cartridges tab pre-filtered by this connection's audit log entries.

6. Capability surface: the adapter layer

The token is necessary but not sufficient. A cartridge that receives a Salesforce access token still needs to know what Salesforce can do, how to call it, and which response fields matter. If every cartridge author re-derives that from Salesforce's docs, the abstraction has failed.

Why this layer exists

Without an adapter, the cartridge becomes a Salesforce expert. It hardcodes /services/data/v59.0/query. It builds query strings. It parses Salesforce's slightly-non-standard JSON. The next cartridge integrating Salesforce repeats every line of that. When Salesforce bumps its API version, the cartridges break in N places, not one.

With an adapter, the cartridge calls sf.soql('SELECT Id FROM Account'). The adapter owns the version, the URL shape, the error decoding, the pagination, the rate-limit handling. Cartridges treat Salesforce as a verb library, not as an HTTP server.

Two halves to a capability

Declared (data, in the SSM provider manifest)

"capabilities": [
  { "name": "soql",           "scope_required": "api", "summary": "Run a SOQL query, returns records" },
  { "name": "sobject.get",    "scope_required": "api", "summary": "Read one sobject by id" },
  ...
]

This serves two audiences. Operators see capability availability in the Setup tab (which capabilities a given connection actually enables, given what scopes Salesforce granted). Cartridge authors see a discoverable list of verbs without reading Salesforce docs.

Implemented (code, in the adapter file)

shared/modules/oauth/adapters/
  salesforce.js          # implements every capability for both salesforce-sandbox and salesforce-production
  github.js              # implements GitHub's capability set
  gitbook.js             # implements GitBook's capability set
  monday.js              # implements Monday's capability set
  _index.js              # adapter registry: maps adapter name from manifest to the module

Each adapter is one file, zero npm, fetch + JSON. The adapter is constructed from a connection and a manifest, returns an object whose methods are the named capabilities. Adapters never deal with tokens directly; they receive a thin connection handle that fetches the current valid token from Secrets Manager on demand.

The scope-to-capability gate

This is the subtle part. The connection record stores scopes_granted (the actual scopes Salesforce returned in the token response, which may be a subset of scopes_requested). The adapter factory only attaches methods whose scope_required is in the granted set. Methods that need an ungranted scope still exist on the adapter, but they throw a clear error rather than calling the API and getting a 403.

// Inside salesforce.js (paraphrased)
export function buildAdapter(connection, manifest) {
  const granted = new Set(connection.scopes_granted);
  const adapter = {};
  for (const cap of manifest.capabilities) {
    if (granted.has(cap.scope_required)) {
      adapter[cap.name] = wireImplementation(cap.name, connection);
    } else {
      adapter[cap.name] = () => {
        throw new Error(
          `Capability ${cap.name} requires scope ${cap.scope_required}, ` +
          `which was not granted on this connection. Reconnect from Setup with broader scopes.`
        );
      };
    }
  }
  return adapter;
}

Calling sf.bulk.query(...) on a connection that did not get the api scope fails fast in the Lambda with a debuggable message, instead of round-tripping to Salesforce for a 403.

What an operator sees in Setup

The connection row in the Setup table gains a Capabilities column showing what is actually available on each connection.

What a cartridge author sees

Opening shared/modules/oauth/adapters/salesforce.js in the editor shows the entire Salesforce surface as one file with JSdoc on every method. The cartridge author never looks up Salesforce API version numbers, endpoint paths, or quirks of the JSON shape.

/**
 * Run a SOQL query against this Salesforce connection.
 *
 * @param {string} soql          A SOQL query string
 * @param {object} [opts]
 * @param {number} [opts.limit]  Max records (default: no client-side limit)
 * @returns {Promise<{ totalSize: number, done: boolean, records: object[] }>}
 *
 * Example:
 *   const r = await sf.soql('SELECT Id, Name FROM Account LIMIT 10');
 *   for (const row of r.records) console.log(row.Name);
 */
async function soql(soql, opts = {}) { ... }

Capability matrix for the v1 + roadmap providers

Audit log of capability use

Every capability call emits a structured oauth-capability-complete log line. Shape: { msg, user, provider_id, capability, durationMs, success, error? }. The obs Cartridges tab joins these by user and by provider so an audit reviewer can answer "what did mtang do on Salesforce yesterday" in one query.

Why this is not an SDK in the npm sense

An adapter is a thin verb wrapper. It does not model Salesforce's full object tree. It does not generate types. It does not parse SOQL or validate it. It passes the SOQL string through to Salesforce. If Salesforce supports it, it works. If not, the cartridge gets Salesforce's error back. We are not in the business of being a Salesforce SDK; we are in the business of giving cartridges a clean verb surface so that token plumbing and capability discovery are not their problem.

This is the right altitude for v1 and probably forever. If a cartridge does something exotic with Salesforce, it can use sf.raw(method, path, body) as the escape hatch, which every adapter provides.

7. Token refresh: why scheduler beats lazy

Tokens expire. Some pattern keeps them current. Four candidates, ranked.

The sweeper

Same primitives as the obs narrative sweeper: wrapScheduledHandler writes start + end run records to DDB; the Step 6.k watchdog fires SES alerts if the sweeper itself misses its SLA.

Cost: at 10-minute cadence, the sweeper invokes 4,320 times per month. Lambda billing for a 5-second function call at 128 MB is roughly $0.10 / month. Negligible.

8. Salesforce as the first provider

Salesforce drives the abstraction shape because it carries every OAuth wrinkle. Once it works, every other provider is a subset.

Connected App setup (one-time, manual)

Pre-requisite, done by a Salesforce admin in Salesforce Setup → App Manager:

1. Create New Connected App.
2. Enable OAuth Settings. Callback URL: https://console.paycargo.org/api/oauth/callback/salesforce-sandbox (plus the production callback for the prod Connected App).
3. OAuth Scopes: api, refresh_token, offline_access.
4. Enable PKCE (Require Proof Key for Code Exchange).
5. Refresh Token Policy: "Refresh token is valid until revoked" (lets the sweeper renew indefinitely).
6. Copy consumer key (client_id) and consumer secret (client_secret).
7. Hand off to the Forge operator; the operator runs a Terraform PR to write these into Secrets Manager at /forge/oauth/clients/salesforce-sandbox.

Two Connected Apps: one in the Salesforce sandbox instance, one in production. Two provider manifests in SSM. Two distinct client_id pairs. No environment toggling in code.

Salesforce-specific response handling

Salesforce's token response carries instance_url, which differs per Salesforce org. Cartridges making API calls need it ({instance_url}/services/data/...). The provider manifest's metadata_fields: ["instance_url", "id"] tells the OAuth flow to persist it as connection metadata. The cartridge consumption helper returns it alongside the access token:

const sf = await getOAuthConnection('salesforce-sandbox');
// {
//   accessToken: 'sf-eyJ...',
//   metadata: {
//     instance_url: 'https://paycargodev.my.salesforce.com',
//     id: 'https://test.salesforce.com/id/00DXX.../005XX...'
//   },
//   expiresAt: '2026-06-10T22:17:00Z'
// }

OAuth flow sequence

9. Zero-npm OAuth implementation

The Console Lambda has the same no-npm rule as every cartridge Lambda. Node 20's built-ins cover everything.

Helpers live under shared/modules/oauth/, staged into lambda/_shared/oauth/ at apply time via the same local_file + archive_file pattern we established in shared/modules/.

shared/modules/oauth/
  README.md                # zero-npm doctrine + provider manifest shape + capability convention
  flow.js                  # createOAuthFlow({provider, userJwt}): { authorize_url, complete(code, state) }
  pkce.js                  # generatePkce() and verify helpers
  store.js                 # readConnection / writeConnection / deleteConnection (DDB + Secrets Manager)
  refresh.js               # refreshConnection({connection_id}): rotates tokens
  client.js                # getOAuthClient(provider_id, jwt): returns a runtime adapter
  adapters/
    _index.js              # adapter registry (manifest.adapter -> module)
    salesforce.js          # implements Salesforce capability set; used by both sandbox and production manifests
    github.js              # roadmap
    gitbook.js             # roadmap
    monday.js              # roadmap

10. Where everything lives

Console API routes

11. Cartridge consumption pattern

// In any cartridge's lambda/handler.js
import { getOAuthClient } from './_shared/oauth/client.js';

// jwtPayload is from the existing JWT verify path
const sf = await getOAuthClient('salesforce-sandbox', jwtPayload.username);
if (!sf) {
  return jsonResponse(409, {
    error: 'No Salesforce connection',
    detail: 'Open the Console Setup tab and click Connect on Salesforce Sandbox.',
    setupUrl: 'https://console.paycargo.org/setup',
  });
}

// Adapter exposes Salesforce capabilities as typed verbs.
// No fetch, no URLs, no Authorization header, no refresh handling.
const accounts = await sf.soql('SELECT Id, Name FROM Account LIMIT 10');
for (const row of accounts.records) console.log(row.Name);

const opp = await sf.sobject.create('Opportunity', {
  Name:      'Q3 PayCargo Pilot',
  CloseDate: '2026-09-30',
  StageName: 'Prospecting',
});

getOAuthClient reads the connection row, fetches the provider manifest, loads the named adapter, and constructs a runtime object whose methods are the capabilities granted by the connection's scopes. The cartridge calls verbs, never raw HTTP.

What the cartridge does not do

• Does not call provider's authorize / token / refresh endpoints directly.
• Does not store any provider credentials.
• Does not handle the OAuth redirect dance.
• Does not care about PKCE.
• Does not know the provider URLs or API version numbers.
• Does not build query strings or set the Authorization header.
• Does not decide which verbs are available (the scope gate decides).

This is the abstraction's whole point. Cartridge code is small, declarative, and never changes when we swap providers or add new ones. The adapter and the manifest move; the cartridge does not.

Escape hatch

Every adapter ships a raw(method, path, body?) capability for the cases where the cartridge needs something the adapter does not yet expose. sf.raw('GET', '/services/data/v59.0/limits'). Same auth plumbing, same audit log. When a cartridge uses the escape hatch more than twice, the next adapter PR adds that capability natively.

12. Security

13. Scope: v1 in / deferred

14. Ship order

Five small PRs, each independently apply-able, each with a clear rollback.

1. PR 1: shared/modules/oauth/ — helpers + first adapter. No TF, no Lambda wiring. Includes flow.js, pkce.js, store.js, refresh.js, client.js, and adapters/salesforce.js with the seven Salesforce capabilities and the raw escape hatch. Smoke-tested locally against a unit harness; integration smoke deferred to PR 5. Same shape as the JWT verify migration that landed earlier this week.
2. PR 2: substrate/modules/platform/oauth/ — foundation module. KMS grants, Secrets Manager namespace, DDB key shape, SSM parameter prefix, refresh-sweeper Lambda + EventBridge Schedule (off until provider manifests land), audit log group.
3. PR 3: Salesforce provider manifests + Connected App secrets — two SSM parameters, two Secrets Manager entries. Requires the Salesforce admin to have created the Connected Apps first (manual prereq).
4. PR 4: Console Lambda + Setup tab UI — six new routes, Setup tab markup + JS. JWT-gated. Calls the helpers from PR 1, reads providers from PR 3.
5. PR 5: First cartridge consumption — whichever cartridge needs Salesforce first (likely a future sales/quoting cartridge) imports getOAuthConnection and makes its first Salesforce call. End-to-end smoke test of the whole stack.

Custom domain prerequisite: PR 4's Setup tab and PR 5's cartridge token consumption work fine on the CloudFront URLs, but the Connected App callback URLs (configured in Salesforce admin) reference console.paycargo.org. That domain needs to be live before PR 3 lands. See the DNS / cert wire-up PR currently in flight.

Decisions locked

References

• Step 6.g — The Console
• Step 6.i — Cartridge extended metadata
• Step 6.k — Scheduled-jobs substrate (EventBridge + DLQ + watchdog)
• Step 4.5.b — Three-layer browser-to-Lambda defense
• Step 3 — Network egress allowlist