@cleocode/core 2026.6.12 → 2026.6.14

package/dist/store/service-host-matcher.js

@@ -0,0 +1,127 @@
+/**
+ * Service host/path → provider matcher (T11940 · M2-W3 · AC1).
+ *
+ * EP-UNIVERSAL-SERVICE-VAULT (epic T11765 · saga SG-VAULT-CORE T10409). The first
+ * half of the injection-at-tool-boundary seam: given the host (and optional path)
+ * of an outbound request a harness tool is about to make, resolve which
+ * {@link ServiceProviderDef} (and therefore which `service_connections` provider)
+ * the request's host belongs to, plus the matching {@link ServiceHostRule} that
+ * declares HOW the credential is injected (the {@link HostAuthStrategy}).
+ *
+ * Pure, side-effect-free, decrypt-free: it consults ONLY the declarative
+ * {@link SERVICE_PROVIDERS} registry (frozen DATA in `@cleocode/contracts`). It
+ * never opens a DB, never decrypts, never touches the network — so it is NOT a DB
+ * chokepoint concern (Gate 3) and carries no credential material.
+ *
+ * ## Matching model (mirrors onecli `apps.rs::match_host`)
+ *
+ * `host` matches EXACTLY against `ServiceHostRule.host`, with one well-defined
+ * suffix case: a rule host beginning with `.` (or a registry host that is a bare
+ * apex like `amazonaws.com`) matches any sub-domain suffix — used for wildcard
+ * families like AWS. `pathPrefix`, when present on a rule, further narrows the
+ * match to requests whose path starts with it (e.g. the legacy
+ * `www.googleapis.com/gmail/` endpoints). When multiple rules match, the MOST
+ * SPECIFIC wins: a `pathPrefix` rule beats a host-only rule, and a longer
+ * `pathPrefix` beats a shorter one.
+ *
+ * @module store/service-host-matcher
+ * @task T11940
+ * @epic T11765
+ * @saga T10409
+ * @see @cleocode/contracts/vault/service-provider — SERVICE_PROVIDERS + ServiceHostRule
+ * @see ./service-injection.ts — the injector that consumes a match to mutate a request
+ */
+import { SERVICE_PROVIDERS, } from '@cleocode/contracts';
+/**
+ * Normalize a host: lowercase, strip a trailing dot, strip a `:port` suffix.
+ *
+ * @param host - The raw host (may carry a port / trailing dot / mixed case).
+ * @returns The normalized host for exact / suffix comparison.
+ */
+function normalizeHost(host) {
+    const lower = host.trim().toLowerCase().replace(/\.$/, '');
+    const colon = lower.indexOf(':');
+    return colon === -1 ? lower : lower.slice(0, colon);
+}
+/**
+ * Does `requestHost` match a rule's `ruleHost`?
+ *
+ * Exact match, OR a suffix match when the rule host is an apex domain (no
+ * sub-domain label of its own, e.g. `amazonaws.com`) — then any `*.amazonaws.com`
+ * host matches. An exact-equality rule host with sub-domain labels
+ * (e.g. `api.github.com`) matches ONLY that host.
+ */
+function hostMatches(requestHost, ruleHost) {
+    if (requestHost === ruleHost)
+        return true;
+    // Apex-domain suffix match: a two-label rule host (`amazonaws.com`) matches any
+    // deeper sub-domain (`s3.us-east-1.amazonaws.com`). A rule host with three or
+    // more labels (`api.github.com`) is treated as exact-only.
+    const ruleLabels = ruleHost.split('.');
+    if (ruleLabels.length === 2 && requestHost.endsWith(`.${ruleHost}`)) {
+        return true;
+    }
+    return false;
+}
+/** Does a rule's optional `pathPrefix` admit `requestPath`? (absent prefix ⇒ yes) */
+function pathMatches(requestPath, rule) {
+    if (rule.pathPrefix === undefined)
+        return true;
+    return requestPath.startsWith(rule.pathPrefix);
+}
+/**
+ * Resolve an outbound request's host (+ optional path) to the matching service
+ * provider + host rule, or `null` when no provider claims the host (T11940 AC1).
+ *
+ * When several rules match (e.g. a host-only rule and a `pathPrefix` rule on the
+ * same host), the MOST SPECIFIC wins: a rule with a `pathPrefix` beats one without,
+ * and a longer `pathPrefix` beats a shorter one. Among equally-specific matches the
+ * first registry entry wins (stable iteration order of {@link SERVICE_PROVIDERS}).
+ *
+ * @param host - The request host (e.g. `api.github.com`; a `:port` / trailing dot
+ *   is tolerated).
+ * @param path - The request path (defaults to `/`); narrows `pathPrefix` rules.
+ * @returns The {@link ServiceHostMatch}, or `null` when no provider matches.
+ * @task T11940
+ */
+export function matchServiceHost(host, path = '/') {
+    const reqHost = normalizeHost(host);
+    const reqPath = path.startsWith('/') ? path : `/${path}`;
+    let best = null;
+    let bestScore = -1;
+    for (const provider of Object.values(SERVICE_PROVIDERS)) {
+        for (const rule of provider.hostRules) {
+            if (!hostMatches(reqHost, rule.host))
+                continue;
+            if (!pathMatches(reqPath, rule))
+                continue;
+            // Specificity score: path-prefixed rules outrank host-only; longer prefix wins.
+            const score = rule.pathPrefix === undefined ? 0 : rule.pathPrefix.length;
+            if (score > bestScore) {
+                bestScore = score;
+                best = { provider, rule, strategy: rule.strategy };
+            }
+        }
+    }
+    return best;
+}
+/**
+ * Resolve the matching provider for a full URL string (convenience over
+ * {@link matchServiceHost} that parses the URL's host + path).
+ *
+ * @param url - The absolute request URL (e.g. `https://api.github.com/user`).
+ * @returns The {@link ServiceHostMatch}, or `null` when the URL is unparseable or
+ *   no provider matches.
+ * @task T11940
+ */
+export function matchServiceUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    return matchServiceHost(parsed.host, parsed.pathname);
+}
+//# sourceMappingURL=service-host-matcher.js.map

package/dist/store/service-host-matcher.js.map

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

package/dist/store/service-injection.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Service-credential injection at the harness tool boundary (T11940 · M2-W3).
+ *
+ * EP-UNIVERSAL-SERVICE-VAULT (epic T11765 · saga SG-VAULT-CORE T10409). The second
+ * half of the injection seam: given an outbound HTTP request a harness tool is about
+ * to make, resolve the matching service connection, refresh it if expired, and apply
+ * the declarative {@link InjectionRule} model — materializing the secret ONLY at the
+ * wire inside the sealed handle's `fetch()`.
+ *
+ * ## NO MITM proxy (AC4)
+ *
+ * The seam is the IN-PROCESS tool boundary — {@link injectServiceCredentials} is a
+ * pure function over a {@link OutboundRequest} descriptor. There is NO CONNECT proxy,
+ * no man-in-the-middle process, no port to bind: the harness calls this immediately
+ * before it builds its `fetch()`, gets back the mutated headers/URL, and makes the
+ * call itself. The function neither performs nor intercepts any network I/O.
+ *
+ * ## Trust-gated, refresh-first (AC2)
+ *
+ * Credential resolution delegates to {@link selfHealConnection} (the store's
+ * resolve-path): it runs the trust gate FIRST (a denied agent gets `null` with NO
+ * decrypt) and transparently REFRESHES a past-expiry token before sealing. Only on a
+ * passing gate is a {@link SealedCredential} returned.
+ *
+ * ## Decrypt-only-at-wire + redaction (AC3)
+ *
+ * The credential is a {@link SealedCredential}: its `fetch()` is the SOLE decrypt
+ * point and is invoked HERE, exactly once, when an injection rule needs the token —
+ * the materialized plaintext is consumed in-place to build the header/param value and
+ * NEVER bound to a returned field, logged, or serialized. The only credential-derived
+ * string that crosses the diagnostic boundary is the non-secret
+ * {@link SealedCredential.tokenPreview} ({@link InjectionDiagnostic.tokenPreview}).
+ *
+ * @module store/service-injection
+ * @task T11940
+ * @epic T11765
+ * @saga T10409
+ * @see ./service-host-matcher.ts — host/path → provider resolution (AC1)
+ * @see ./service-oauth.ts — `selfHealConnection` (trust-gated, refresh-first sealed resolve)
+ * @see ../llm/sealed-credential.ts — `makeSealedCredential` (the shared egress handle)
+ */
+import type { HostAuthStrategy, InjectionRule } from '@cleocode/contracts';
+import { type ServiceOAuthDeps } from './service-oauth.js';
+/**
+ * The mutable outbound-request descriptor the injector reads and rewrites. The
+ * harness builds this from the request it is about to make; after injection it
+ * uses the (possibly rewritten) `url` + `headers` to call `fetch()`.
+ */
+export interface OutboundRequest {
+    /** The absolute request URL (host + path drive provider matching). */
+    readonly url: string;
+    /** The request headers (case-insensitive on the wire; stored case-preserving). */
+    readonly headers: Readonly<Record<string, string>>;
+}
+/** The header/URL mutations an injection produced (the rewritten request). */
+export interface InjectedRequest {
+    /** The (possibly rewritten) request URL — `set-param` rules add query params. */
+    readonly url: string;
+    /** The rewritten request headers with the credential injected. */
+    readonly headers: Record<string, string>;
+}
+/** A NON-SECRET diagnostic describing what an injection did (safe to log). */
+export interface InjectionDiagnostic {
+    /** The matched provider key (e.g. `github`), or `null` when no provider matched. */
+    readonly provider: string | null;
+    /** The connection label that was injected, or `null` when none. */
+    readonly label: string | null;
+    /** The injection strategy applied, or `null` when no provider matched. */
+    readonly strategy: HostAuthStrategy | null;
+    /**
+     * The NON-SECRET redacted token preview ({@link SealedCredential.tokenPreview}) —
+     * the ONLY credential-derived string permitted to cross a logging/diagnostic
+     * boundary (≤ last 4 chars). `null` when no credential was injected.
+     */
+    readonly tokenPreview: string | null;
+    /** Whether a transparent refresh fired before injection. */
+    readonly refreshed: boolean;
+}
+/** The result of {@link injectServiceCredentials}. */
+export interface InjectionResult {
+    /**
+     * Whether a credential was injected. `false` when no provider claims the host, or
+     * the agent's trust gate denied / the connection is missing-or-uncredentialed —
+     * in which case `request` is the ORIGINAL request, untouched.
+     */
+    readonly injected: boolean;
+    /** The (possibly rewritten) request — mutated only when {@link injected}. */
+    readonly request: InjectedRequest;
+    /** A non-secret diagnostic (safe to log). */
+    readonly diagnostic: InjectionDiagnostic;
+}
+/** Parameters for {@link injectServiceCredentials}. */
+export interface InjectServiceCredentialsParams {
+    /** The agent making the outbound request (trust-gated). */
+    readonly agentId: string;
+    /** The outbound request descriptor to inject into. */
+    readonly request: OutboundRequest;
+    /**
+     * The connection label to use for the matched provider (defaults to `'default'`).
+     * A provider can have several labelled connections; the caller selects which.
+     */
+    readonly label?: string;
+    /** Out-of-band manual-approval flag forwarded to the trust gate. */
+    readonly approved?: boolean;
+    /**
+     * Seconds of pre-expiry headroom at which to refresh (forwarded to
+     * {@link selfHealConnection}). Defaults to 0 (refresh only once past expiry).
+     */
+    readonly skewSeconds?: number;
+}
+/**
+ * Translate a host rule's {@link HostAuthStrategy} into the concrete
+ * {@link InjectionRule} list applied for a matched request.
+ *
+ * This is the SSoT mapping strategy → injection actions:
+ *  - `bearer` — `Authorization: Bearer <token>` (overwrite any existing auth).
+ *  - `basic-x-access-token` — `Authorization: Basic base64("x-access-token:<token>")`
+ *    (GitHub git-over-HTTPS).
+ *  - `header` — the token goes via a named header rather than `Authorization`; the
+ *    concrete header is provider-declared (`credentialHeaders`), so here we still
+ *    set `Authorization: Bearer` as the safe default and let a provider that needs a
+ *    custom header carry it via its `credentialHeaders` (a later breadth task wires
+ *    those). All three strategies first strip a stale `Authorization` the tool may
+ *    have emitted (`remove-header`) so the vault credential is authoritative.
+ *
+ * @param strategy - The matched host rule's injection strategy.
+ * @returns The ordered injection actions.
+ */
+export declare function injectionRulesForStrategy(strategy: HostAuthStrategy): readonly InjectionRule[];
+/**
+ * Resolve + inject a service credential into an outbound request at the tool
+ * boundary (T11940 · AC1–AC4).
+ *
+ * Flow:
+ *  1. Match the request URL's host/path to a provider ({@link matchServiceUrl}).
+ *     No match → return the original request untouched (`injected: false`).
+ *  2. Resolve the connection via {@link selfHealConnection} — trust-gated +
+ *     refresh-first. Denied / missing / uncredentialed → original request untouched.
+ *  3. Materialize the token ONCE at the wire (`sealed.fetch()`) and apply the
+ *     {@link injectionRulesForStrategy} rule list to a COPY of the headers + a
+ *     parsed URL. The plaintext is consumed in-place; only the non-secret
+ *     {@link SealedCredential.tokenPreview} reaches the diagnostic.
+ *
+ * @param params - The agent, request, label, and refresh knobs.
+ * @param deps - Injectable OAuth/clock/vault deps (test seam; a fake vault proves
+ *   injection + redaction without a real `cleo.db` or network).
+ * @returns The {@link InjectionResult} — the (possibly rewritten) request + a
+ *   non-secret diagnostic.
+ * @task T11940
+ */
+export declare function injectServiceCredentials(params: InjectServiceCredentialsParams, deps?: ServiceOAuthDeps): Promise<InjectionResult>;
+//# sourceMappingURL=service-injection.d.ts.map

package/dist/store/service-injection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-injection.d.ts","sourceRoot":"","sources":["../../src/store/service-injection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAoB,MAAM,qBAAqB,CAAC;AAE7F,OAAO,EAEL,KAAK,gBAAgB,EAEtB,MAAM,oBAAoB,CAAC;AAE5B;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;CAC1C;AAED,uDAAuD;AACvD,MAAM,WAAW,8BAA8B;IAC7C,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAKD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,aAAa,EAAE,CAM9F;AAqED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,8BAA8B,EACtC,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,eAAe,CAAC,CA0E1B"}

package/dist/store/service-injection.js

@@ -0,0 +1,225 @@
+/**
+ * Service-credential injection at the harness tool boundary (T11940 · M2-W3).
+ *
+ * EP-UNIVERSAL-SERVICE-VAULT (epic T11765 · saga SG-VAULT-CORE T10409). The second
+ * half of the injection seam: given an outbound HTTP request a harness tool is about
+ * to make, resolve the matching service connection, refresh it if expired, and apply
+ * the declarative {@link InjectionRule} model — materializing the secret ONLY at the
+ * wire inside the sealed handle's `fetch()`.
+ *
+ * ## NO MITM proxy (AC4)
+ *
+ * The seam is the IN-PROCESS tool boundary — {@link injectServiceCredentials} is a
+ * pure function over a {@link OutboundRequest} descriptor. There is NO CONNECT proxy,
+ * no man-in-the-middle process, no port to bind: the harness calls this immediately
+ * before it builds its `fetch()`, gets back the mutated headers/URL, and makes the
+ * call itself. The function neither performs nor intercepts any network I/O.
+ *
+ * ## Trust-gated, refresh-first (AC2)
+ *
+ * Credential resolution delegates to {@link selfHealConnection} (the store's
+ * resolve-path): it runs the trust gate FIRST (a denied agent gets `null` with NO
+ * decrypt) and transparently REFRESHES a past-expiry token before sealing. Only on a
+ * passing gate is a {@link SealedCredential} returned.
+ *
+ * ## Decrypt-only-at-wire + redaction (AC3)
+ *
+ * The credential is a {@link SealedCredential}: its `fetch()` is the SOLE decrypt
+ * point and is invoked HERE, exactly once, when an injection rule needs the token —
+ * the materialized plaintext is consumed in-place to build the header/param value and
+ * NEVER bound to a returned field, logged, or serialized. The only credential-derived
+ * string that crosses the diagnostic boundary is the non-secret
+ * {@link SealedCredential.tokenPreview} ({@link InjectionDiagnostic.tokenPreview}).
+ *
+ * @module store/service-injection
+ * @task T11940
+ * @epic T11765
+ * @saga T10409
+ * @see ./service-host-matcher.ts — host/path → provider resolution (AC1)
+ * @see ./service-oauth.ts — `selfHealConnection` (trust-gated, refresh-first sealed resolve)
+ * @see ../llm/sealed-credential.ts — `makeSealedCredential` (the shared egress handle)
+ */
+import { matchServiceUrl } from './service-host-matcher.js';
+import { selfHealConnection, } from './service-oauth.js';
+/** The default connection label when the caller does not specify one. */
+const DEFAULT_LABEL = 'default';
+/**
+ * Translate a host rule's {@link HostAuthStrategy} into the concrete
+ * {@link InjectionRule} list applied for a matched request.
+ *
+ * This is the SSoT mapping strategy → injection actions:
+ *  - `bearer` — `Authorization: Bearer <token>` (overwrite any existing auth).
+ *  - `basic-x-access-token` — `Authorization: Basic base64("x-access-token:<token>")`
+ *    (GitHub git-over-HTTPS).
+ *  - `header` — the token goes via a named header rather than `Authorization`; the
+ *    concrete header is provider-declared (`credentialHeaders`), so here we still
+ *    set `Authorization: Bearer` as the safe default and let a provider that needs a
+ *    custom header carry it via its `credentialHeaders` (a later breadth task wires
+ *    those). All three strategies first strip a stale `Authorization` the tool may
+ *    have emitted (`remove-header`) so the vault credential is authoritative.
+ *
+ * @param strategy - The matched host rule's injection strategy.
+ * @returns The ordered injection actions.
+ */
+export function injectionRulesForStrategy(strategy) {
+    // Always strip any stale Authorization the tool emitted, then set the vault one.
+    return [
+        { kind: 'remove-header', name: 'Authorization' },
+        { kind: 'set-header', name: 'Authorization', valueSource: 'token', framing: strategy },
+    ];
+}
+/** Build the framed `Authorization` value for a token under a host strategy. */
+function frameToken(token, framing) {
+    switch (framing) {
+        case 'basic-x-access-token': {
+            const basic = Buffer.from(`x-access-token:${token}`, 'utf8').toString('base64');
+            return `Basic ${basic}`;
+        }
+        default:
+            // `bearer`, `header` (default), and an absent framing all bearer-frame.
+            return `Bearer ${token}`;
+    }
+}
+/** Find a header key case-insensitively; returns the existing key or `undefined`. */
+function findHeaderKey(headers, name) {
+    const lower = name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === lower)
+            return key;
+    }
+    return undefined;
+}
+/**
+ * Apply one injection rule to a header bag + URL, materializing the token from the
+ * sealed handle ONLY when a value-bearing rule needs it.
+ *
+ * The plaintext token (when materialized) lives ONLY as the local `token` binding
+ * for the duration of this call and is consumed in-place into the header/param —
+ * it is never returned, logged, or stored.
+ */
+function applyRule(rule, headers, url, token) {
+    switch (rule.kind) {
+        case 'remove-header': {
+            const existing = findHeaderKey(headers, rule.name);
+            if (existing !== undefined)
+                delete headers[existing];
+            return;
+        }
+        case 'set-header': {
+            const existing = findHeaderKey(headers, rule.name);
+            const value = rule.valueSource === 'token' ? frameToken(token, rule.framing) : token;
+            if (existing !== undefined)
+                delete headers[existing];
+            headers[rule.name] = value;
+            return;
+        }
+        case 'replace-header': {
+            const existing = findHeaderKey(headers, rule.name);
+            if (existing === undefined)
+                return; // only replace a present header
+            headers[existing] = rule.valueSource === 'token' ? frameToken(token, rule.framing) : token;
+            return;
+        }
+        case 'set-param': {
+            url.searchParams.set(rule.name, token);
+            return;
+        }
+    }
+}
+/** Whether the rule set contains any value-bearing rule (needs a materialized token). */
+function needsToken(rules) {
+    return rules.some((r) => r.kind !== 'remove-header');
+}
+/**
+ * Resolve + inject a service credential into an outbound request at the tool
+ * boundary (T11940 · AC1–AC4).
+ *
+ * Flow:
+ *  1. Match the request URL's host/path to a provider ({@link matchServiceUrl}).
+ *     No match → return the original request untouched (`injected: false`).
+ *  2. Resolve the connection via {@link selfHealConnection} — trust-gated +
+ *     refresh-first. Denied / missing / uncredentialed → original request untouched.
+ *  3. Materialize the token ONCE at the wire (`sealed.fetch()`) and apply the
+ *     {@link injectionRulesForStrategy} rule list to a COPY of the headers + a
+ *     parsed URL. The plaintext is consumed in-place; only the non-secret
+ *     {@link SealedCredential.tokenPreview} reaches the diagnostic.
+ *
+ * @param params - The agent, request, label, and refresh knobs.
+ * @param deps - Injectable OAuth/clock/vault deps (test seam; a fake vault proves
+ *   injection + redaction without a real `cleo.db` or network).
+ * @returns The {@link InjectionResult} — the (possibly rewritten) request + a
+ *   non-secret diagnostic.
+ * @task T11940
+ */
+export async function injectServiceCredentials(params, deps = {}) {
+    const label = params.label ?? DEFAULT_LABEL;
+    const originalRequest = {
+        url: params.request.url,
+        headers: { ...params.request.headers },
+    };
+    // 1. Match the host/path to a provider.
+    const match = matchServiceUrl(params.request.url);
+    if (match === null) {
+        return {
+            injected: false,
+            request: originalRequest,
+            diagnostic: {
+                provider: null,
+                label: null,
+                strategy: null,
+                tokenPreview: null,
+                refreshed: false,
+            },
+        };
+    }
+    // 2. Resolve the connection — trust-gated + refresh-first (sealed on allow).
+    const healOptions = {
+        agentId: params.agentId,
+        provider: match.provider.provider,
+        label,
+        ...(params.approved !== undefined ? { approved: params.approved } : {}),
+        ...(params.skewSeconds !== undefined ? { skewSeconds: params.skewSeconds } : {}),
+    };
+    const heal = await selfHealConnection(healOptions, deps);
+    const sealed = heal.sealed;
+    if (sealed === null) {
+        // Denied / missing / uncredentialed — leave the request untouched.
+        return {
+            injected: false,
+            request: originalRequest,
+            diagnostic: {
+                provider: match.provider.provider,
+                label,
+                strategy: match.strategy,
+                tokenPreview: null,
+                refreshed: heal.refreshed,
+            },
+        };
+    }
+    // 3. Apply the strategy's injection rules. Materialize the token at the wire ONCE
+    //    (the SOLE decrypt point) and consume it in-place; it never escapes this scope.
+    const rules = injectionRulesForStrategy(match.strategy);
+    const headers = { ...params.request.headers };
+    const url = new URL(params.request.url);
+    let token = '';
+    if (needsToken(rules)) {
+        const decrypted = await sealed.fetch();
+        token = decrypted.value;
+    }
+    for (const rule of rules) {
+        applyRule(rule, headers, url, token);
+    }
+    // The local `token` goes out of scope here — never returned or logged.
+    return {
+        injected: true,
+        request: { url: url.toString(), headers },
+        diagnostic: {
+            provider: match.provider.provider,
+            label,
+            strategy: match.strategy,
+            tokenPreview: sealed.tokenPreview,
+            refreshed: heal.refreshed,
+        },
+    };
+}
+//# sourceMappingURL=service-injection.js.map

package/dist/store/service-injection.js.map

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