@atlasauth/pca-connectors 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atlas Authorization
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @atlasauth/pca-connectors
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The connector catalog for Proof-Carrying Authority (PCA): a declarative registry of outbound SaaS providers as data manifests, plus the authorize-URL, code-exchange and refresh helpers that feed the `@atlasauth/pca-connect` token vault. Wiring a new outbound tool is a manifest edit, and every connection minted here is bound to a PCA capability: the stored token is only released when a verified PCActn proves authority over the provider and scopes.
+
+Built-in manifests: Airtable, Atlassian, Dropbox, GitHub, Google, HubSpot, Linear, Microsoft, Notion, Salesforce, Shopify, Slack, Snowflake, Stripe, Zoom. Each manifest declares the authorize and token URLs, default scopes, PKCE, how the access token is placed on a request, and refresh behaviour.
+
+This package is the code layer only. It never makes the outbound API call and ships no consent UI.
+
+## Install
+
+```sh
+npm i @atlasauth/pca-connectors
+```
+
+Depends on `@atlasauth/pca` and `@atlasauth/pca-connect` (installed automatically).
+
+## Usage
+
+```ts
+import { TokenVault } from '@atlasauth/pca-connect';
+import {
+  listProviders, buildAuthorizeUrl, exchangeCode, buildVaultProviders, getProvider, applyAccessToken,
+} from '@atlasauth/pca-connectors';
+
+listProviders().map((p) => p.id); // ['airtable', 'atlassian', 'dropbox', 'github', 'google', ...]
+
+// 1. Send the user to the provider. Keep `state` and `pkce.verifier` for the callback.
+const { url, state, pkce } = buildAuthorizeUrl('google', {
+  clientId: process.env.GOOGLE_CLIENT_ID!,
+  redirectUri: 'https://app.example/callback',
+  scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
+});
+
+// 2. A vault whose auto-refresh config is derived from the manifests.
+const vault = new TokenVault({
+  providers: buildVaultProviders({ google: { clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret: process.env.GOOGLE_CLIENT_SECRET } }),
+  fetch, // your HTTP transport (the global fetch works)
+});
+
+// 3. On callback, exchange the code and store a capability-bound connection.
+await exchangeCode({
+  providerId: 'google',
+  clientId: process.env.GOOGLE_CLIENT_ID!,
+  clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+  code, // from the redirect
+  redirectUri: 'https://app.example/callback',
+  codeVerifier: pkce?.verifier,
+  scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
+  fetch,
+  bind: { vault, agentId, authority: { principal } }, // b64u keys: the agent, and the root the capability chain must start at
+});
+
+// Later, a verified PCActn releases the token via vault.getConnectionToken(...); then:
+const header = applyAccessToken(getProvider('google')!, accessToken); // { kind: 'header', name: 'Authorization', value: 'Bearer ...' }
+```
+
+Custom providers: `registerProvider(manifest)` validates a manifest and adds it to the default registry, or create your own `ProviderRegistry`. Manifests with a `{var}` placeholder in their URLs (such as Shopify) take `vars: { shop: 'acme' }`.
+
+## API
+
+- Registry: `ProviderRegistry`, `defaultRegistry`, `registerProvider`, `getProvider`, `listProviders`, `validateManifest`, `assertManifest`
+- Authorization: `buildAuthorizeUrl`, `pkceChallenge`, `applyAccessToken`, `substituteVars`
+- Tokens: `exchangeCode`, `refresh`, `manifestToProviderConfig`, `buildVaultProviders`
+- `providers` namespace with the built-in manifests
+
+## Status
+
+The manifests are data describing each provider's public OAuth endpoints; verify the scopes and endpoints for your own app registration before relying on them. Refresh behaviour and scope narrowing vary by provider and are declared per manifest. Cryptography in PCA is unaudited.
+
+Source and issues: https://github.com/Atlas-Authorization/pca
+
+## License
+
+MIT - see LICENSE

package/dist/authorize.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The authorization-request side of a connector: turn a declarative {@link ProviderManifest} into a correct
+ * OAuth 2.0 authorize URL (with PKCE when the provider wants it), and describe how the resulting access
+ * token is presented on an outbound API call.
+ */
+import { type ProviderManifest } from './manifest';
+import { type ProviderRegistry } from './registry';
+/** Caller-supplied PKCE material (RFC 7636). When omitted, {@link buildAuthorizeUrl} generates it. */
+export interface PkceParams {
+    /** The high-entropy `code_verifier` (43–128 unreserved chars). */
+    verifier: string;
+    /** Challenge method. Default `'S256'`. */
+    method?: 'S256' | 'plain';
+}
+/** The PKCE values used for an authorize request; keep `verifier` to complete the code exchange. */
+export interface PkceResult {
+    verifier: string;
+    challenge: string;
+    method: 'S256' | 'plain';
+}
+export interface BuildAuthorizeUrlOptions {
+    clientId: string;
+    redirectUri: string;
+    /** Requested scopes. Defaults to the manifest's `defaultScopes`. */
+    scopes?: string[];
+    /** CSRF `state`. A random value is generated when omitted; the value used is returned. */
+    state?: string;
+    /**
+     * PKCE control. `true` forces PKCE (auto-generating a verifier); an object supplies the verifier;
+     * `false` disables it; omitted follows the manifest's `pkce` flag.
+     */
+    pkce?: boolean | PkceParams;
+    /** Substitutions for `{var}` placeholders in the manifest URLs (e.g. `{ shop: 'acme' }`). */
+    vars?: Record<string, string>;
+    /** Registry to resolve `providerId` against. Defaults to the shared {@link defaultRegistry}. */
+    registry?: ProviderRegistry;
+    /** Extra authorize-request parameters, merged after the manifest's `authParams`. */
+    extraParams?: Record<string, string>;
+}
+/** A built authorize URL plus the `state` and (if used) PKCE values the caller must retain for the exchange. */
+export interface AuthorizeUrl {
+    url: string;
+    state: string;
+    pkce?: PkceResult;
+}
+/** The S256 code challenge for a verifier: base64url(SHA-256(ASCII(verifier))), unpadded (RFC 7636 §4.2). */
+export declare function pkceChallenge(verifier: string, method?: 'S256' | 'plain'): string;
+/** Substitute `{var}` placeholders in `url`. Throws {@link ConnectorError} when a used var is not supplied. */
+export declare function substituteVars(url: string, vars: Record<string, string> | undefined): string;
+/**
+ * Build the OAuth 2.0 authorization-request URL for `providerId`. Always emits `response_type=code`,
+ * `client_id`, `redirect_uri`, `scope`, and `state`; adds `code_challenge` + `code_challenge_method` when
+ * PKCE is in effect, and merges the manifest's `authParams` then the caller's `extraParams`. Scopes are
+ * joined with the manifest's `scopeSeparator` (default space). Pure and synchronous.
+ */
+export declare function buildAuthorizeUrl(providerId: string, options: BuildAuthorizeUrlOptions): AuthorizeUrl;
+/** Where a manifest says an access token belongs on an outbound request. */
+export type AppliedToken = {
+    kind: 'header';
+    name: string;
+    value: string;
+} | {
+    kind: 'query';
+    name: string;
+    value: string;
+};
+/**
+ * Describe how `accessToken` is attached to a provider API call, per the manifest's `tokenPlacement`:
+ * `bearer` → `Authorization: Bearer <token>`; `header` → the custom `headerName`; `query` → the `queryParam`.
+ * Returns a value the caller applies to its own request; this package never performs the outbound call.
+ */
+export declare function applyAccessToken(manifest: ProviderManifest, accessToken: string): AppliedToken;

package/dist/authorize.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * The authorization-request side of a connector: turn a declarative {@link ProviderManifest} into a correct
+ * OAuth 2.0 authorize URL (with PKCE when the provider wants it), and describe how the resulting access
+ * token is presented on an outbound API call.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pkceChallenge = pkceChallenge;
+exports.substituteVars = substituteVars;
+exports.buildAuthorizeUrl = buildAuthorizeUrl;
+exports.applyAccessToken = applyAccessToken;
+const pca_1 = require("@atlasauth/pca");
+const manifest_1 = require("./manifest");
+const registry_1 = require("./registry");
+/** 32 bytes of CSPRNG entropy, base64url (unpadded). */
+function randomToken(bytes = 32) {
+    const b = new Uint8Array(bytes);
+    globalThis.crypto.getRandomValues(b);
+    return (0, pca_1.b64u)(b);
+}
+/** The S256 code challenge for a verifier: base64url(SHA-256(ASCII(verifier))), unpadded (RFC 7636 §4.2). */
+function pkceChallenge(verifier, method = 'S256') {
+    return method === 'plain' ? verifier : (0, pca_1.b64u)((0, pca_1.sha256)((0, pca_1.utf8)(verifier)));
+}
+/** Substitute `{var}` placeholders in `url`. Throws {@link ConnectorError} when a used var is not supplied. */
+function substituteVars(url, vars) {
+    return url.replace(/\{(\w+)\}/g, (_full, name) => {
+        const v = vars === undefined ? undefined : vars[name];
+        if (v === undefined)
+            throw new manifest_1.ConnectorError(`missing URL variable '{${name}}'`);
+        return v;
+    });
+}
+function encodeForm(params) {
+    return params.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&');
+}
+/**
+ * Build the OAuth 2.0 authorization-request URL for `providerId`. Always emits `response_type=code`,
+ * `client_id`, `redirect_uri`, `scope`, and `state`; adds `code_challenge` + `code_challenge_method` when
+ * PKCE is in effect, and merges the manifest's `authParams` then the caller's `extraParams`. Scopes are
+ * joined with the manifest's `scopeSeparator` (default space). Pure and synchronous.
+ */
+function buildAuthorizeUrl(providerId, options) {
+    const registry = options.registry ?? registry_1.defaultRegistry;
+    const manifest = registry.require(providerId);
+    const scopes = options.scopes ?? manifest.defaultScopes;
+    const separator = manifest.scopeSeparator ?? ' ';
+    const state = options.state ?? randomToken();
+    const params = [
+        ['response_type', 'code'],
+        ['client_id', options.clientId],
+        ['redirect_uri', options.redirectUri],
+    ];
+    if (scopes.length > 0)
+        params.push(['scope', scopes.join(separator)]);
+    params.push(['state', state]);
+    // PKCE: enabled when explicitly requested, when a verifier object is passed, or (unless disabled) when
+    // the manifest declares it.
+    const wantPkce = options.pkce === false ? false : options.pkce !== undefined ? true : manifest.pkce === true;
+    let pkce;
+    if (wantPkce) {
+        const verifier = typeof options.pkce === 'object' ? options.pkce.verifier : randomToken();
+        const method = typeof options.pkce === 'object' ? options.pkce.method ?? 'S256' : 'S256';
+        const challenge = pkceChallenge(verifier, method);
+        params.push(['code_challenge', challenge], ['code_challenge_method', method]);
+        pkce = { verifier, challenge, method };
+    }
+    for (const [k, v] of Object.entries(manifest.authParams ?? {}))
+        params.push([k, v]);
+    for (const [k, v] of Object.entries(options.extraParams ?? {}))
+        params.push([k, v]);
+    const base = substituteVars(manifest.authorizeUrl, options.vars);
+    const url = `${base}${base.includes('?') ? '&' : '?'}${encodeForm(params)}`;
+    const result = { url, state };
+    if (pkce !== undefined)
+        result.pkce = pkce;
+    return result;
+}
+/**
+ * Describe how `accessToken` is attached to a provider API call, per the manifest's `tokenPlacement`:
+ * `bearer` → `Authorization: Bearer <token>`; `header` → the custom `headerName`; `query` → the `queryParam`.
+ * Returns a value the caller applies to its own request; this package never performs the outbound call.
+ */
+function applyAccessToken(manifest, accessToken) {
+    switch (manifest.tokenPlacement) {
+        case 'bearer':
+            return { kind: 'header', name: 'Authorization', value: `Bearer ${accessToken}` };
+        case 'header': {
+            if (manifest.headerName === undefined)
+                throw new manifest_1.ConnectorError(`manifest '${manifest.id}' is header-placed but has no headerName`);
+            return { kind: 'header', name: manifest.headerName, value: accessToken };
+        }
+        case 'query': {
+            if (manifest.queryParam === undefined)
+                throw new manifest_1.ConnectorError(`manifest '${manifest.id}' is query-placed but has no queryParam`);
+            return { kind: 'query', name: manifest.queryParam, value: accessToken };
+        }
+    }
+}
+//# sourceMappingURL=authorize.js.map

package/dist/authorize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.js","sourceRoot":"","sources":["../src/authorize.ts"],"names":[],"mappings":"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"}

package/dist/exchange.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The token side of a connector: exchange an authorization code (or a refresh token) at a provider's token
+ * endpoint and FEED the `@atlasauth/pca-connect` vault, so every stored connection is bound to a PCA
+ * capability. A connection minted here is unusable until a verified Proof-Carrying Action proves authority
+ * over the provider and that the requested scopes are a subset of what the capability grants — that
+ * capability binding is the differentiator a plain token vault lacks.
+ *
+ * The vault's OWN auto-refresh (inside `getConnectionToken`) is wired from the same manifests via
+ * {@link manifestToProviderConfig} / {@link buildVaultProviders}, so the catalog is the single source of
+ * truth for both the initial grant and later refreshes.
+ */
+import type { ProviderConfig, StoredConnection, TokenVault, VaultFetch } from '@atlasauth/pca-connect';
+import { type ProviderManifest } from './manifest';
+import { type ProviderRegistry } from './registry';
+/** How a minted connection is stored and bound to a PCA capability in the vault. */
+export interface ConnectionBinding {
+    vault: TokenVault;
+    /** b64u public key of the agent — the capability chain's LEAF holder this connection belongs to. */
+    agentId: string;
+    /** Vault connection id. Defaults to the vault's own `defaultConnectionId`. */
+    connectionId?: string;
+    authority: {
+        /** b64u public key the capability chain must be rooted at (the PCActn's `cap_chain[0].issuer`). */
+        principal: string;
+        /** Scopes the capability must cover. Defaults to the requested scopes (least privilege). */
+        scopes?: string[];
+        /** When set, the PCActn's signed `aud` must equal this resource-server id. */
+        audience?: string;
+    };
+}
+export interface ExchangeCodeArgs {
+    providerId: string;
+    clientId: string;
+    clientSecret?: string;
+    /** The authorization code returned to the redirect URI. */
+    code: string;
+    redirectUri: string;
+    /** The PKCE `code_verifier` used for the authorize request (required when the provider uses PKCE). */
+    codeVerifier?: string;
+    /** Scopes requested (and the least-privilege authority the connection is bound to). Defaults to the manifest's. */
+    scopes?: string[];
+    /** Injectable HTTP transport (same contract as the vault's `fetch`). */
+    fetch: VaultFetch;
+    /** How to store + capability-bind the resulting connection. */
+    bind: ConnectionBinding;
+    /** Clock, epoch ms. Defaults to `Date.now`. */
+    now?: number;
+    /** Registry to resolve `providerId` against. Defaults to {@link defaultRegistry}. */
+    registry?: ProviderRegistry;
+    /** `{var}` substitutions for the manifest token URL. */
+    vars?: Record<string, string>;
+    /** Extra static token-request form parameters. */
+    extraParams?: Record<string, string>;
+}
+export interface RefreshArgs {
+    providerId: string;
+    clientId: string;
+    clientSecret?: string;
+    /** The refresh token to present (the vault does not expose stored refresh tokens without a PCActn). */
+    refreshToken: string;
+    /** Scopes to request / re-bind. Defaults to the manifest's `defaultScopes`. */
+    scopes?: string[];
+    fetch: VaultFetch;
+    bind: ConnectionBinding;
+    now?: number;
+    registry?: ProviderRegistry;
+    vars?: Record<string, string>;
+    extraParams?: Record<string, string>;
+}
+/**
+ * Exchange an authorization code for tokens and store a capability-bound connection in the vault. The
+ * requested scopes become the connection's least-privilege authority; the connection is unusable until a
+ * verified PCActn proves a capability covering them.
+ */
+export declare function exchangeCode(args: ExchangeCodeArgs): Promise<StoredConnection>;
+/**
+ * Refresh an access token at the provider's refresh endpoint and re-store the capability-bound connection.
+ * Throws when the manifest declares `refresh.mode === 'none'`. Scope narrowing is sent only when the
+ * manifest opts in. The authority binding is preserved from `bind` (re-asserting least privilege).
+ */
+export declare function refresh(args: RefreshArgs): Promise<StoredConnection>;
+/** Per-provider client credentials used to derive a vault {@link ProviderConfig}. */
+export interface ProviderCredentials {
+    clientId: string;
+    clientSecret?: string;
+    /** `{var}` substitutions for the refresh token endpoint (e.g. `{ shop: 'acme' }`). */
+    vars?: Record<string, string>;
+}
+/**
+ * Derive the `@atlasauth/pca-connect` {@link ProviderConfig} the vault uses for its OWN auto-refresh, from a
+ * manifest + credentials. This is how the catalog drives the vault's internal refresh: the manifest's token
+ * endpoint, scope-narrowing flag and extra params flow straight into the vault. Throws when the manifest
+ * does not support refresh.
+ */
+export declare function manifestToProviderConfig(manifest: ProviderManifest, creds: ProviderCredentials): ProviderConfig;
+/**
+ * Build the vault's `providers` map (provider id → {@link ProviderConfig}) from a set of configured
+ * providers, skipping any whose manifest cannot refresh. Pass the result to `new TokenVault({ providers })`.
+ */
+export declare function buildVaultProviders(credsById: Record<string, ProviderCredentials>, registry?: ProviderRegistry): Record<string, ProviderConfig>;

package/dist/exchange.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * The token side of a connector: exchange an authorization code (or a refresh token) at a provider's token
+ * endpoint and FEED the `@atlasauth/pca-connect` vault, so every stored connection is bound to a PCA
+ * capability. A connection minted here is unusable until a verified Proof-Carrying Action proves authority
+ * over the provider and that the requested scopes are a subset of what the capability grants — that
+ * capability binding is the differentiator a plain token vault lacks.
+ *
+ * The vault's OWN auto-refresh (inside `getConnectionToken`) is wired from the same manifests via
+ * {@link manifestToProviderConfig} / {@link buildVaultProviders}, so the catalog is the single source of
+ * truth for both the initial grant and later refreshes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exchangeCode = exchangeCode;
+exports.refresh = refresh;
+exports.manifestToProviderConfig = manifestToProviderConfig;
+exports.buildVaultProviders = buildVaultProviders;
+const pca_1 = require("@atlasauth/pca");
+const manifest_1 = require("./manifest");
+const registry_1 = require("./registry");
+const authorize_1 = require("./authorize");
+/** Default access-token lifetime assumed when the provider returns neither `expires_in` nor a JWT `exp`. */
+const DEFAULT_TOKEN_LIFETIME_MS = 3_600_000;
+/** Read own property `k` off `o` as `unknown`, without a cast. */
+function prop(o, k) {
+    return Object.prototype.hasOwnProperty.call(o, k) ? Reflect.get(o, k) : undefined;
+}
+function errText(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** Standard base64 (padded) of `s` — for HTTP Basic client authentication (RFC 6749 §2.3.1). */
+function basicAuthHeader(clientId, clientSecret) {
+    let s = (0, pca_1.b64u)((0, pca_1.utf8)(`${clientId}:${clientSecret}`)).replace(/-/g, '+').replace(/_/g, '/');
+    while (s.length % 4 !== 0)
+        s += '=';
+    return `Basic ${s}`;
+}
+function formEncode(params) {
+    return Object.entries(params)
+        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+        .join('&');
+}
+/** Parse an OAuth token-endpoint JSON body. Fails closed: a missing/empty `access_token` is a hard error. */
+function parseTokenResponse(body, provider) {
+    if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+        throw new manifest_1.ConnectorError(`[${provider}] token endpoint returned a non-object body`);
+    }
+    const accessToken = prop(body, 'access_token');
+    if (typeof accessToken !== 'string' || accessToken.length === 0) {
+        throw new manifest_1.ConnectorError(`[${provider}] token endpoint response has no access_token`);
+    }
+    const out = { accessToken };
+    const expiresIn = prop(body, 'expires_in');
+    if (typeof expiresIn === 'number' && Number.isFinite(expiresIn) && expiresIn > 0)
+        out.expiresInSecs = expiresIn;
+    const refreshToken = prop(body, 'refresh_token');
+    if (typeof refreshToken === 'string' && refreshToken.length > 0)
+        out.refreshToken = refreshToken;
+    const scope = prop(body, 'scope');
+    if (typeof scope === 'string' && scope.trim().length > 0)
+        out.scopes = scope.trim().split(/[\s,]+/);
+    return out;
+}
+/** POST a form to a token endpoint via the injectable transport and parse the response (fail-closed). */
+async function postToken(manifest, tokenEndpoint, params, clientSecret, fetchImpl) {
+    const headers = {
+        'content-type': 'application/x-www-form-urlencoded',
+        accept: 'application/json',
+    };
+    const body = { ...params };
+    if (manifest.clientAuth === 'basic') {
+        // Client credentials move to the Authorization header; they must not also appear in the body.
+        if (clientSecret === undefined)
+            throw new manifest_1.ConnectorError(`[${manifest.id}] clientAuth 'basic' requires a clientSecret`);
+        const clientId = body['client_id'];
+        if (clientId === undefined)
+            throw new manifest_1.ConnectorError(`[${manifest.id}] missing client_id for basic auth`);
+        headers['authorization'] = basicAuthHeader(clientId, clientSecret);
+        delete body['client_id'];
+        delete body['client_secret'];
+    }
+    let res;
+    try {
+        res = await fetchImpl(tokenEndpoint, { method: 'POST', headers, body: formEncode(body) });
+    }
+    catch (e) {
+        throw new manifest_1.ConnectorError(`[${manifest.id}] token transport error: ${errText(e)}`);
+    }
+    if (!res.ok) {
+        let detail = '';
+        try {
+            detail = (await res.text()).slice(0, 256);
+        }
+        catch {
+            detail = '<unreadable body>';
+        }
+        throw new manifest_1.ConnectorError(`[${manifest.id}] token endpoint ${res.status}: ${detail}`);
+    }
+    let json;
+    try {
+        json = await res.json();
+    }
+    catch (e) {
+        throw new manifest_1.ConnectorError(`[${manifest.id}] unparseable token JSON: ${errText(e)}`);
+    }
+    return parseTokenResponse(json, manifest.id);
+}
+/** Store the token result in the vault, bound to the PCA capability authority. */
+async function storeConnection(manifest, parsed, requested, bind, now, priorRefreshToken) {
+    const expiresAt = parsed.expiresInSecs !== undefined ? now + parsed.expiresInSecs * 1000 : now + DEFAULT_TOKEN_LIFETIME_MS;
+    // Scopes the stored token actually carries: the provider's echo wins; else the requested set.
+    const granted = parsed.scopes ?? requested;
+    // Token rotation: keep the prior refresh token unless the provider issued a new one.
+    const refreshToken = parsed.refreshToken ?? priorRefreshToken;
+    return bind.vault.putConnection({
+        agentId: bind.agentId,
+        provider: manifest.id,
+        accessToken: parsed.accessToken,
+        expiresAt,
+        scopes: granted,
+        authority: {
+            principal: bind.authority.principal,
+            scopes: bind.authority.scopes ?? requested,
+            ...(bind.authority.audience !== undefined ? { audience: bind.authority.audience } : {}),
+        },
+        ...(bind.connectionId !== undefined ? { connectionId: bind.connectionId } : {}),
+        ...(refreshToken !== undefined ? { refreshToken } : {}),
+    });
+}
+/**
+ * Exchange an authorization code for tokens and store a capability-bound connection in the vault. The
+ * requested scopes become the connection's least-privilege authority; the connection is unusable until a
+ * verified PCActn proves a capability covering them.
+ */
+async function exchangeCode(args) {
+    const registry = args.registry ?? registry_1.defaultRegistry;
+    const manifest = registry.require(args.providerId);
+    const now = args.now ?? Date.now();
+    const requested = args.scopes ?? manifest.defaultScopes;
+    if (manifest.pkce === true && args.codeVerifier === undefined) {
+        throw new manifest_1.ConnectorError(`[${manifest.id}] provider uses PKCE; a codeVerifier is required to exchange the code`);
+    }
+    const params = {
+        grant_type: 'authorization_code',
+        code: args.code,
+        redirect_uri: args.redirectUri,
+        client_id: args.clientId,
+        ...(args.clientSecret !== undefined ? { client_secret: args.clientSecret } : {}),
+        ...(args.codeVerifier !== undefined ? { code_verifier: args.codeVerifier } : {}),
+        ...(args.extraParams ?? {}),
+    };
+    const tokenEndpoint = (0, authorize_1.substituteVars)(manifest.tokenUrl, args.vars);
+    const parsed = await postToken(manifest, tokenEndpoint, params, args.clientSecret, args.fetch);
+    return storeConnection(manifest, parsed, requested, args.bind, now);
+}
+/**
+ * Refresh an access token at the provider's refresh endpoint and re-store the capability-bound connection.
+ * Throws when the manifest declares `refresh.mode === 'none'`. Scope narrowing is sent only when the
+ * manifest opts in. The authority binding is preserved from `bind` (re-asserting least privilege).
+ */
+async function refresh(args) {
+    const registry = args.registry ?? registry_1.defaultRegistry;
+    const manifest = registry.require(args.providerId);
+    if (manifest.refresh.mode === 'none') {
+        throw new manifest_1.ConnectorError(`[${manifest.id}] provider does not support token refresh`);
+    }
+    const now = args.now ?? Date.now();
+    const requested = args.scopes ?? manifest.defaultScopes;
+    const params = {
+        grant_type: 'refresh_token',
+        refresh_token: args.refreshToken,
+        client_id: args.clientId,
+        ...(args.clientSecret !== undefined ? { client_secret: args.clientSecret } : {}),
+        ...(manifest.refresh.extraParams ?? {}),
+        ...(args.extraParams ?? {}),
+    };
+    if (manifest.refresh.supportsScopeNarrowing === true && requested.length > 0) {
+        params['scope'] = requested.join(manifest.scopeSeparator ?? ' ');
+    }
+    const tokenEndpoint = (0, authorize_1.substituteVars)(manifest.refresh.tokenEndpoint ?? manifest.tokenUrl, args.vars);
+    const parsed = await postToken(manifest, tokenEndpoint, params, args.clientSecret, args.fetch);
+    return storeConnection(manifest, parsed, requested, args.bind, now, args.refreshToken);
+}
+/**
+ * Derive the `@atlasauth/pca-connect` {@link ProviderConfig} the vault uses for its OWN auto-refresh, from a
+ * manifest + credentials. This is how the catalog drives the vault's internal refresh: the manifest's token
+ * endpoint, scope-narrowing flag and extra params flow straight into the vault. Throws when the manifest
+ * does not support refresh.
+ */
+function manifestToProviderConfig(manifest, creds) {
+    if (manifest.refresh.mode === 'none') {
+        throw new manifest_1.ConnectorError(`[${manifest.id}] provider does not support token refresh; no ProviderConfig`);
+    }
+    const config = {
+        tokenEndpoint: (0, authorize_1.substituteVars)(manifest.refresh.tokenEndpoint ?? manifest.tokenUrl, creds.vars),
+        clientId: creds.clientId,
+    };
+    if (creds.clientSecret !== undefined)
+        config.clientSecret = creds.clientSecret;
+    if (manifest.refresh.supportsScopeNarrowing !== undefined)
+        config.supportsScopeNarrowing = manifest.refresh.supportsScopeNarrowing;
+    if (manifest.refresh.extraParams !== undefined)
+        config.extraParams = { ...manifest.refresh.extraParams };
+    return config;
+}
+/**
+ * Build the vault's `providers` map (provider id → {@link ProviderConfig}) from a set of configured
+ * providers, skipping any whose manifest cannot refresh. Pass the result to `new TokenVault({ providers })`.
+ */
+function buildVaultProviders(credsById, registry = registry_1.defaultRegistry) {
+    const out = {};
+    for (const [id, creds] of Object.entries(credsById)) {
+        const manifest = registry.require(id);
+        if (manifest.refresh.mode === 'none')
+            continue;
+        out[id] = manifestToProviderConfig(manifest, creds);
+    }
+    return out;
+}
+//# sourceMappingURL=exchange.js.map

package/dist/exchange.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exchange.js","sourceRoot":"","sources":["../src/exchange.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@atlasauth/pca-connectors` — the connector catalog for Proof-Carrying Authority.
+ *
+ * A declarative registry of outbound SaaS providers (Google, GitHub, Slack, …) as data manifests, plus the
+ * authorize-URL / code-exchange / refresh helpers that feed the `@atlasauth/pca-connect` token vault. Wiring
+ * a new outbound tool is a manifest edit, and EVERY connection minted here is bound to a PCA capability —
+ * so every outbound token a tool call presents is a proof-carrying, least-privilege capability, not an
+ * ambient secret. That capability binding is the property Composio / Descope / Auth0 Token Vault lack.
+ *
+ * This is the CODE layer; a hosted consent UI is a separate product piece built on top of it.
+ */
+export { type TokenPlacement, type RefreshMode, type ClientAuthMethod, type RefreshSpec, type ProviderManifest, type ManifestValidation, ConnectorError, ManifestValidationError, UnknownProviderError, validateManifest, assertManifest, } from './manifest';
+export { ProviderRegistry, createDefaultRegistry, defaultRegistry, registerProvider, getProvider, listProviders, } from './registry';
+export { type PkceParams, type PkceResult, type BuildAuthorizeUrlOptions, type AuthorizeUrl, type AppliedToken, buildAuthorizeUrl, pkceChallenge, substituteVars, applyAccessToken, } from './authorize';
+export { type ConnectionBinding, type ExchangeCodeArgs, type RefreshArgs, type ProviderCredentials, exchangeCode, refresh, manifestToProviderConfig, buildVaultProviders, } from './exchange';
+export * as providers from './providers';
+export { type ConnectionToken, type StoredConnection, type ProviderConfig, type VaultFetch, type VaultHttpRequest, type VaultHttpResponse, TokenVault, InMemoryConnectionStore, oauthScopeCaveat, grantedOAuthScopes, NotAuthorizedError, ScopeExceededError, ExpiredNoRefreshError, RefreshFailedError, UnknownConnectionError, VaultError, } from '@atlasauth/pca-connect';