@cleocode/contracts 2026.6.12 → 2026.6.14

package/dist/vault/service-provider.d.ts

@@ -0,0 +1,343 @@
+/**
+ * Universal service-vault — declarative service-provider registry (types + DATA).
+ *
+ * EP-UNIVERSAL-SERVICE-VAULT (epic T11765 · saga SG-VAULT-CORE T10409 · M2 W1a ·
+ * task T11937). The **service** half of the universal vault: machine-wide OAuth /
+ * API credentials for third-party SERVICES (github, google, notion, figma, …) —
+ * distinct from the LLM-provider credential pool (`accounts`, T11709) which holds
+ * model-API keys. A {@link ServiceProviderDef} is a purely declarative description
+ * of one connectable service: its stable key, display label, auth shape, and the
+ * default OAuth endpoints/scopes the (later) OAuth dance (T11939) will drive.
+ *
+ * ## Why this lives in `@cleocode/contracts` (Gate 10 purity)
+ *
+ * This module is **types + frozen DATA only**. {@link SERVICE_PROVIDERS} is a
+ * `const` record literal (no bodied function, no zod schema, no type guard) — it
+ * is configuration data, exactly like a routing table, so it satisfies the
+ * contracts-purity gate (`lint-no-runtime-in-contracts`). The runtime that
+ * CONSUMES the registry (the store, the trust gate, the OAuth flow) lives in
+ * `@cleocode/core`; this file never imports from core and carries no side effects.
+ *
+ * ## Pattern, not census (T11937 vs T11938)
+ *
+ * Only **github** and **google** are seeded here, deliberately — they prove the
+ * declarative pattern (one PKCE provider with a fixed loopback, one classic
+ * web-OAuth provider) before the fan-out to ~40 services in the follow-up
+ * (T11938). Adding a service is a single DATA entry; no code change.
+ *
+ * @module contracts/vault/service-provider
+ * @task T11937
+ * @epic T11765
+ * @saga T10409
+ * @see ../llm/oauth.js — `ProviderOAuthConfig` / `OAuthMode` (reused here)
+ * @see ../llm/sealed-credential.js — `SealedCredential` (the egress handle a resolved service credential is wrapped in)
+ */
+import type { ProviderOAuthConfig } from '../llm/oauth.js';
+/**
+ * Auth shape a service uses to obtain credentials.
+ *
+ * - `oauth2` — classic OAuth 2.0 Authorization Code grant (e.g. github web flow).
+ * - `oauth2-pkce` — OAuth 2.0 Authorization Code + PKCE (RFC 7636), for CLI /
+ *   headless flows (e.g. google installed-app flow).
+ * - `api-key` — a long-lived API token pasted/imported directly (no OAuth dance).
+ *
+ * The value drives which fields of {@link ServiceProviderDef.oauth} are required
+ * and which OAuth code path (T11939) runs for the service.
+ *
+ * @task T11937
+ */
+export declare const SERVICE_AUTH_KINDS: readonly ["oauth2", "oauth2-pkce", "api-key"];
+/** TypeScript union derived from {@link SERVICE_AUTH_KINDS}. */
+export type ServiceAuthKind = (typeof SERVICE_AUTH_KINDS)[number];
+/**
+ * Discriminant naming the refresh GRANT a provider uses (T11938 AC3).
+ *
+ * The OAuth flow (T11939) branches on this value to pick the refresh code path:
+ *
+ *  - `refresh-token` — the standard OAuth 2.0 `grant_type=refresh_token` exchange
+ *    (RFC 6749 §6), shaped by {@link RefreshConfig.bodyFormat} /
+ *    {@link RefreshConfig.clientAuth}. The common case (google, atlassian, …).
+ *  - `github-app` — a GitHub App installation token: sign an RS256 JWT with the
+ *    app private key, then POST `/app/installations/{id}/access_tokens`.
+ *  - `service-account-jwt` — a Google service-account: sign an RS256 JWT and
+ *    exchange it via `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`.
+ *  - `client-credentials` — the OAuth 2.0 `grant_type=client_credentials` grant
+ *    (RFC 6749 §4.4), Basic-auth client id/secret (e.g. MongoDB Atlas SAs).
+ *
+ * @task T11938
+ */
+export declare const REFRESH_KINDS: readonly ["refresh-token", "github-app", "service-account-jwt", "client-credentials"];
+/** TypeScript union derived from {@link REFRESH_KINDS}. */
+export type RefreshKind = (typeof REFRESH_KINDS)[number];
+/**
+ * Body encoding for a `refresh-token` token-endpoint POST.
+ *
+ * - `form` — `application/x-www-form-urlencoded` (OAuth 2.0 default; google).
+ * - `json` — `application/json` (required by Atlassian / Notion).
+ *
+ * @task T11938
+ */
+export type RefreshBodyFormat = 'form' | 'json';
+/**
+ * How the OAuth client credentials are presented on a `refresh-token` POST.
+ *
+ * - `body` — `client_id` + `client_secret` carried IN the request body (default).
+ * - `basic-auth` — `Authorization: Basic base64(client_id:client_secret)` header
+ *   (Notion, Supabase).
+ *
+ * @task T11938
+ */
+export type RefreshClientAuth = 'body' | 'basic-auth';
+/**
+ * Declarative refresh configuration for a `refresh-token` provider (T11938 AC1).
+ *
+ * Pure data: the token endpoint, the body encoding, and how the client
+ * credentials are presented. The OAuth flow (T11939) reads this to drive the
+ * `grant_type=refresh_token` exchange WITHOUT any per-provider code. The
+ * `kind` discriminant selects the broader grant (the three special variants
+ * — github-app / service-account-jwt / client-credentials — set `kind` and
+ * leave `bodyFormat`/`clientAuth` at their `form`/`body` defaults; their grant
+ * mechanics are not refresh-token-shaped).
+ *
+ * Cannibalized from onecli `apps.rs::RefreshConfig` (DATA only — the Rust
+ * `reqwest`/env-var resolution is re-implemented in TS in T11939).
+ *
+ * @task T11938
+ */
+export interface RefreshConfig {
+    /** Which refresh GRANT this provider uses ({@link RefreshKind}). */
+    readonly kind: RefreshKind;
+    /**
+     * Token endpoint the refresh exchange POSTs to. For `refresh-token` /
+     * `client-credentials`; the JWT variants use a fixed provider endpoint and may
+     * leave this as the canonical value for documentation.
+     */
+    readonly tokenUrl: string;
+    /** Body encoding for a `refresh-token` exchange. Defaults to `form`. */
+    readonly bodyFormat?: RefreshBodyFormat;
+    /** Client-credential presentation for a `refresh-token` exchange. Defaults to `body`. */
+    readonly clientAuth?: RefreshClientAuth;
+}
+/**
+ * Auth strategy a host rule applies when a resolved credential is injected into
+ * an outbound request to a matched host.
+ *
+ * - `bearer` — `Authorization: Bearer <token>` (the OAuth default).
+ * - `basic-x-access-token` — `Authorization: Basic base64("x-access-token:<token>")`
+ *   (GitHub git-over-HTTPS).
+ * - `header` — the token is injected via a named header rather than `Authorization`
+ *   (paired with {@link ServiceProviderDef.credentialHeaders}).
+ *
+ * Declarative only in this milestone — the injecting proxy is a later epic.
+ *
+ * @task T11938
+ */
+export type HostAuthStrategy = 'bearer' | 'basic-x-access-token' | 'header';
+/**
+ * One host-match rule declaring which upstream hosts a provider's credential is
+ * valid for and how it is injected (T11938 AC1/AC4 — every provider declares a
+ * non-empty {@link ServiceProviderDef.hostRules}).
+ *
+ * `host` is matched EXACTLY (no wildcards in this milestone). `pathPrefix`, when
+ * set, narrows the rule to requests under that path (e.g. the legacy
+ * `www.googleapis.com/gmail/` endpoint). Cannibalized from onecli
+ * `apps.rs::HostRule` (DATA only).
+ *
+ * @task T11938
+ */
+export interface ServiceHostRule {
+    /** Exact upstream host this rule matches (e.g. `'api.github.com'`). */
+    readonly host: string;
+    /** Optional path prefix narrowing the rule (e.g. `'/gmail/'`). */
+    readonly pathPrefix?: string;
+    /** How the credential is injected for a matched request. */
+    readonly strategy: HostAuthStrategy;
+}
+/**
+ * One declarative injection action applied to an outbound request when a resolved
+ * service credential is injected at the harness tool boundary (T11940 · M2-W3).
+ *
+ * A discriminated union over the action `kind`. The injector
+ * ({@link import('@cleocode/core').injectServiceCredentials}) materializes the
+ * sealed credential's plaintext ONLY at the wire (inside the action's value
+ * resolver) and applies these mutations to a request descriptor — there is NO MITM
+ * proxy (the seam is the in-process tool boundary, T11940 AC4):
+ *
+ *  - `set-header` — set `name` to the materialized value (overwriting any existing).
+ *  - `replace-header` — set `name` to the value ONLY if the header is already
+ *    present (a no-op when absent — used to swap a placeholder the tool emitted).
+ *  - `remove-header` — delete `name` (e.g. strip a stale `Authorization` before
+ *    re-injecting the vault credential).
+ *  - `set-param` — set the query-string parameter `name` to the materialized value.
+ *
+ * The `valueSource` discriminates WHERE the injected value comes from:
+ * `'token'` (the decrypted access token), `'credential-field'` (a named field of
+ * the credential blob, e.g. an AWS access-key id), or `'metadata'` (a non-secret
+ * connection-metadata key, e.g. a Google project id). `remove-header` carries no
+ * `valueSource` (it injects nothing).
+ *
+ * @task T11940
+ */
+export type InjectionRule = {
+    /** Set a header to the injected value (overwrites any existing). */
+    readonly kind: 'set-header';
+    /** The header name to set. */
+    readonly name: string;
+    /** Where the injected value comes from. */
+    readonly valueSource: InjectionValueSource;
+    /** For `bearer`/`basic-x-access-token` token framing — how to wrap the value. */
+    readonly framing?: HostAuthStrategy;
+} | {
+    /** Set a header ONLY when it is already present (swap a placeholder). */
+    readonly kind: 'replace-header';
+    /** The header name to replace. */
+    readonly name: string;
+    /** Where the injected value comes from. */
+    readonly valueSource: InjectionValueSource;
+    /** For `bearer`/`basic-x-access-token` token framing — how to wrap the value. */
+    readonly framing?: HostAuthStrategy;
+} | {
+    /** Remove a header (injects no value). */
+    readonly kind: 'remove-header';
+    /** The header name to remove. */
+    readonly name: string;
+} | {
+    /** Set a query-string parameter to the injected value. */
+    readonly kind: 'set-param';
+    /** The query-parameter name to set. */
+    readonly name: string;
+    /** Where the injected value comes from. */
+    readonly valueSource: InjectionValueSource;
+};
+/**
+ * Where an {@link InjectionRule}'s injected value is sourced from.
+ *
+ *  - `token` — the decrypted access token (the secret materialized at the wire).
+ *  - `credential-field` — a named field of the credential blob (paired with the
+ *    rule's `name` resolution via {@link ServiceProviderDef.credentialHeaders}).
+ *  - `metadata` — a non-secret connection-metadata key.
+ *
+ * @task T11940
+ */
+export type InjectionValueSource = 'token' | 'credential-field' | 'metadata';
+/**
+ * Inject an HTTP header from a credential-blob field (e.g. a regional API key →
+ * `DD-API-KEY`). Declarative metadata; the injecting proxy is a later epic.
+ *
+ * @task T11938
+ */
+export interface CredentialHeaderRule {
+    /** The credential-blob field whose value is injected. */
+    readonly credentialField: string;
+    /** The HTTP header the value is injected as. */
+    readonly headerName: string;
+}
+/**
+ * Inject an HTTP header from a connection-metadata key (e.g. a project id →
+ * `x-goog-user-project`). Declarative metadata; the injecting proxy is a later
+ * epic.
+ *
+ * @task T11938
+ */
+export interface MetadataHeaderRule {
+    /** The non-secret metadata key whose value is injected. */
+    readonly metadataKey: string;
+    /** The HTTP header the value is injected as. */
+    readonly headerName: string;
+}
+/**
+ * Declarative description of one connectable third-party service.
+ *
+ * A `ServiceProviderDef` is pure configuration: it names a service, describes how
+ * it authenticates, and (for OAuth services) carries the default endpoints and
+ * scopes the OAuth flow will drive. It holds NO secret material — a user's actual
+ * tokens live encrypted in the `service_connections` table; BYOC client secrets
+ * (when the user brings their own OAuth app) live encrypted in `service_configs`.
+ *
+ * @task T11937
+ */
+export interface ServiceProviderDef {
+    /**
+     * Stable provider key (lowercase, kebab) — the join key against
+     * `service_connections.provider` / `service_configs.provider`. NEVER renamed
+     * once shipped (it is persisted in user rows). e.g. `'github'`, `'google'`.
+     */
+    readonly provider: string;
+    /** Human-readable display name for UI / CLI output. e.g. `'GitHub'`. */
+    readonly displayName: string;
+    /** Auth shape this service uses ({@link ServiceAuthKind}). */
+    readonly authKind: ServiceAuthKind;
+    /**
+     * Default OAuth configuration (endpoints + scopes + the public client id of
+     * CLEO's first-party OAuth app). `undefined` for an `api-key`-only service.
+     *
+     * Reuses the LLM-layer {@link ProviderOAuthConfig} shape verbatim — the OAuth
+     * mechanics (PKCE vs classic, endpoints, redirect, extra params) are identical
+     * whether the credential is for a model API or a service API. When the user
+     * supplies their own client id/secret (BYOC, stored in `service_configs`),
+     * those OVERRIDE the `clientId`/`scope` declared here at flow time (T11939).
+     */
+    readonly oauth?: ProviderOAuthConfig;
+    /**
+     * Default space-separated scopes requested when CLEO's first-party app is used
+     * and `oauth.scope` is not overridden by a BYOC `service_configs.settings`.
+     * Mirrors `oauth.scope`; kept as a top-level field so an `api-key` service can
+     * still document the access level a token is expected to carry.
+     */
+    readonly defaultScopes?: string;
+    /**
+     * One-line description of what connecting this service enables. Surfaced in the
+     * connect UI / `cleo service list`. Non-secret.
+     */
+    readonly description: string;
+    /**
+     * Non-empty list of host-match rules (T11938 AC1/AC4) declaring which upstream
+     * hosts this provider's resolved credential is valid for and how it is injected
+     * ({@link ServiceHostRule}). The registry-completeness test asserts EVERY
+     * provider carries at least one rule. Cannibalized from onecli
+     * `apps.rs::AppProvider.host_rules` (DATA only).
+     */
+    readonly hostRules: readonly ServiceHostRule[];
+    /**
+     * Refresh configuration (T11938 AC1/AC3). Present for every `oauth2` /
+     * `oauth2-pkce` provider that can refresh; `undefined` for an `api-key` service
+     * (no token to refresh) or an OAuth service that only re-authorizes. The OAuth
+     * flow (T11939) reads {@link RefreshConfig.kind} to pick the refresh grant.
+     */
+    readonly refresh?: RefreshConfig;
+    /**
+     * Optional header-injection rules sourced from the credential blob (T11938 AC1).
+     * Declarative reach metadata; the injecting proxy is a later epic.
+     */
+    readonly credentialHeaders?: readonly CredentialHeaderRule[];
+    /**
+     * Optional header-injection rules sourced from connection metadata (T11938 AC1).
+     * Declarative reach metadata; the injecting proxy is a later epic.
+     */
+    readonly metadataHeaders?: readonly MetadataHeaderRule[];
+}
+/**
+ * The seeded service-provider registry — **github + google + the ~40-service
+ * census** (T11937 seeds + T11938 breadth).
+ *
+ * Keyed by {@link ServiceProviderDef.provider}. This is the SSoT the store reads
+ * when validating a `connect` and the OAuth flow (T11939) reads for default
+ * endpoints/scopes. The two seeds prove the two OAuth shapes:
+ *
+ *  - **github** — classic OAuth 2.0 web flow (`authKind: 'oauth2'`), fixed
+ *    loopback redirect; user grants `repo`/`read:user` scopes.
+ *  - **google** — installed-app OAuth 2.0 + PKCE (`authKind: 'oauth2-pkce'`),
+ *    loopback redirect; user grants offline-access + the requested API scopes.
+ *
+ * The `clientId` values are PLACEHOLDER public client ids for CLEO's first-party
+ * OAuth apps — the real ids are wired (or BYOC-overridden) when the OAuth dance
+ * lands in T11939. They are NOT secrets (a public OAuth client id is, by design,
+ * embeddable in a distributed CLI).
+ *
+ * Fan-out to the full ~40-service census is the follow-up (T11938): add a DATA
+ * entry here, nothing else.
+ *
+ * @task T11937
+ */
+export declare const SERVICE_PROVIDERS: Readonly<Record<string, ServiceProviderDef>>;
+//# sourceMappingURL=service-provider.d.ts.map

package/dist/vault/service-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-provider.d.ts","sourceRoot":"","sources":["../../src/vault/service-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,+CAAgD,CAAC;AAEhF,gEAAgE;AAChE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAMlE;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,uFAKhB,CAAC;AAEX,2DAA2D;AAC3D,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,YAAY,CAAC;AAEtD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;IACxC,yFAAyF;IACzF,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;CACzC;AAMD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,sBAAsB,GAAG,QAAQ,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,aAAa,GACrB;IACE,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,iFAAiF;IACjF,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACrC,GACD;IACE,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,iFAAiF;IACjF,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACrC,GACD;IACE,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,GACD;IACE,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;CAC5C,CAAC;AAEN;;;;;;;;;GASG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,kBAAkB,GAAG,UAAU,CAAC;AAE7E;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC7D;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC1D;AAysBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAmD1E,CAAC"}