@intx/harness 0.2.2 → 0.3.0

package/README.md

@@ -17,15 +17,19 @@ import {
 } from "@intx/agent";
 import { noopAuditStore, permissiveAuthorize } from "@intx/agent/testing";
 import { createHarness, defineMailTools } from "@intx/harness";
-import { createIsogitStore } from "@intx/storage-isogit";
+import { createIsogitStore } from "@intx/storage-isogit/node";
 
-const mailFactory = defineMailTools(() => ({
-  definitions: myMailTools.definitions,
-  run: (call, signal) => myMailTools.run(call, signal),
-}));
+const mailFactory = defineMailTools(
+  () => ({
+    definitions: myMailTools.definitions,
+    run: (call, signal) => myMailTools.run(call, signal),
+  }),
+  myMailTools.definitions.map((def) => ({ name: def.name })),
+);
 
 const posixFactory = defineTool({
   id: "@my-org/agent/posix",
+  definitions: myPosixTools.definitions.map((def) => ({ name: def.name })),
   factory: () => ({
     definitions: myPosixTools.definitions,
     run: (call, signal) => myPosixTools.run(call, signal),

package/dist/credential-capability.d.ts

@@ -0,0 +1,65 @@
+import { type GrantRule } from "@intx/authz";
+import type { CredentialCapability, CredentialMaterialSource } from "@intx/types";
+import type { ToolCredentialDeclaration } from "@intx/types/package-json";
+import type { CredentialProviderRegistry } from "./credential-providers.js";
+/**
+ * A binding resolved at launch: which credential backs a declared handle, which
+ * provider shapes it, the origin it authenticates to, and how to read its
+ * current material. The material source is an indirection over a mutable cell so
+ * a rotation reaches an already-shaped handle without a rebuild.
+ */
+export interface ResolvedCredentialBinding {
+    /** The credential row id the handle resolved to; the `credential:{id}` the
+     *  use-grant check runs against. */
+    credentialId: string;
+    /** The provider plugin key that shapes this credential's handle. */
+    providerKey: string;
+    /** The provider origin the shaped handle authenticates to. */
+    origin: string;
+    /** Reads the current secret material (rotation indirection). */
+    readCurrentMaterial: CredentialMaterialSource;
+}
+/**
+ * Reconcile a tool package's declared credential handles (its C5 `interchange.
+ * credentials`) against the handles a binding actually resolved for it. A
+ * declared handle with no binding is a launch-blocking misconfiguration -- the
+ * tool needs a credential the definition never bound -- so this fails the launch
+ * loudly rather than letting the gap surface as a resolve-time throw at the
+ * tool's first use. It is the throw-on-missing of `resolve`, pulled earlier to
+ * launch where the whole set is known.
+ */
+export declare function reconcileDeclaredCredentials(consumer: string, declared: readonly ToolCredentialDeclaration[], boundHandles: ReadonlySet<string>): void;
+export interface CredentialCapabilityDeps {
+    /**
+     * The consumer identity of the tool package this capability serves
+     * (`tool:<package>`, from `toolConsumer`). Gate 2 checks each grant's
+     * `{ tool }` condition against this value; an empty identity fails closed.
+     */
+    consumer: string;
+    /** Resolved bindings keyed by the handle the tool declared. */
+    bindings: ReadonlyMap<string, ResolvedCredentialBinding>;
+    /** The registry that shapes a credential into a mediated handle. */
+    providers: CredentialProviderRegistry;
+    /** The grants in effect for this deploy (the consumer's run grants). */
+    grants: GrantRule[];
+}
+/**
+ * A `CredentialCapability` plus a host-only `dispose`. The tool sees only
+ * `resolve`; the host runs `dispose` on teardown to release every handle shaped
+ * through this capability (an http handle holds nothing; a future key-file /
+ * socket handle would).
+ */
+export interface HostCredentialCapability extends CredentialCapability {
+    dispose(): Promise<void>;
+}
+/**
+ * Build the consumer-gated `credentials` capability for one tool package.
+ *
+ * `resolve(handle)` fails closed at every step: an unbound handle throws; a
+ * handle the consumer is not authorized to use throws (Gate 2 -- the same
+ * `authorizeAction` the model-source path uses, here supplied the credential-use
+ * condition registry and this consumer). Only an authorized handle is shaped,
+ * once, and memoized so repeated resolves return the same instance and there is
+ * a single thing to dispose.
+ */
+export declare function createCredentialCapability(deps: CredentialCapabilityDeps): HostCredentialCapability;

package/dist/credential-capability.js

@@ -0,0 +1,98 @@
+// The consumer-gated `credentials` capability: the sub-registry a tool queries
+// by its declared handle to obtain a mediated credential. It is the runtime
+// gate that enforces the `{ tool }` condition on a materialized
+// `credential:{id}` / `use` grant -- the check the launch-time grant
+// materialization sets up but does not itself evaluate.
+//
+// The gate lives here, at the point of use, and fails closed: a handle resolves
+// only when the calling consumer holds `credential:{id}` / `use` with the
+// grant's `{ tool }` condition matching this consumer. The shaping of the
+// handle is delegated to the provider registry; the material is read fresh per
+// use (rotation indirection) from the source the binding carries.
+import { authorizeAction, CREDENTIAL_USE_CONDITIONS, } from "@intx/authz";
+/**
+ * Reconcile a tool package's declared credential handles (its C5 `interchange.
+ * credentials`) against the handles a binding actually resolved for it. A
+ * declared handle with no binding is a launch-blocking misconfiguration -- the
+ * tool needs a credential the definition never bound -- so this fails the launch
+ * loudly rather than letting the gap surface as a resolve-time throw at the
+ * tool's first use. It is the throw-on-missing of `resolve`, pulled earlier to
+ * launch where the whole set is known.
+ */
+export function reconcileDeclaredCredentials(consumer, declared, boundHandles) {
+    const missing = declared
+        .map((declaration) => declaration.handle)
+        .filter((handle) => !boundHandles.has(handle));
+    if (missing.length > 0) {
+        throw new Error(`consumer ${consumer} declares credential handle(s) that no binding resolves: ${missing.join(", ")}`);
+    }
+}
+/**
+ * Build the consumer-gated `credentials` capability for one tool package.
+ *
+ * `resolve(handle)` fails closed at every step: an unbound handle throws; a
+ * handle the consumer is not authorized to use throws (Gate 2 -- the same
+ * `authorizeAction` the model-source path uses, here supplied the credential-use
+ * condition registry and this consumer). Only an authorized handle is shaped,
+ * once, and memoized so repeated resolves return the same instance and there is
+ * a single thing to dispose.
+ */
+export function createCredentialCapability(deps) {
+    // Memoize the in-flight PROMISE, not the resolved handle, so two concurrent
+    // resolves of the same handle share one gate+shape and yield one instance
+    // (caching the value would let both miss the memo and shape twice, orphaning
+    // a handle). A deterministic failure -- unbound handle, denied gate, unknown
+    // provider -- caches too; it stays failed for this deploy, which is correct
+    // since grants do not change mid-deploy.
+    const shaped = new Map();
+    function shapeHandle(handle) {
+        return (async () => {
+            const binding = deps.bindings.get(handle);
+            if (binding === undefined) {
+                throw new Error(`no credential is bound to handle "${handle}" for consumer ${deps.consumer}`);
+            }
+            // Gate 2: fail closed unless the consumer holds credential:{id} / use with
+            // the grant's { tool } condition matching this consumer.
+            const decision = await authorizeAction(deps.grants, `credential:${binding.credentialId}`, "use", { registry: CREDENTIAL_USE_CONDITIONS, consumer: deps.consumer });
+            if (!decision.ok) {
+                throw new Error(`consumer ${deps.consumer} is not authorized to use credential ${binding.credentialId} (${decision.reason})`);
+            }
+            const provider = deps.providers.resolve(binding.providerKey);
+            return provider.shape({
+                origin: binding.origin,
+                readCurrentMaterial: binding.readCurrentMaterial,
+            });
+        })();
+    }
+    return {
+        resolve(handle) {
+            const existing = shaped.get(handle);
+            if (existing !== undefined)
+                return existing;
+            const pending = shapeHandle(handle);
+            shaped.set(handle, pending);
+            return pending;
+        },
+        async dispose() {
+            // Dispose EVERY successfully-shaped handle even if one throws -- a single
+            // bad handle must not strand the rest -- then surface any failures loudly
+            // rather than swallowing them.
+            const settled = await Promise.allSettled([...shaped.values()]);
+            shaped.clear();
+            const errors = [];
+            for (const result of settled) {
+                if (result.status !== "fulfilled")
+                    continue;
+                try {
+                    await result.value.dispose();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            if (errors.length > 0) {
+                throw new AggregateError(errors, "one or more credential handles failed to dispose");
+            }
+        },
+    };
+}

package/dist/credential-providers.d.ts

@@ -0,0 +1,56 @@
+import type { CredentialProvider } from "@intx/types";
+/** Resolves a provider identifier to the plugin that shapes its handles. */
+export interface CredentialProviderRegistry {
+    has(key: string): boolean;
+    resolve(key: string): CredentialProvider;
+}
+/**
+ * Build a registry from a list of providers. The list is copied into a private
+ * `Map`, so callers cannot mutate the set after construction and lookups never
+ * reach `Object.prototype`. A duplicate key is a wiring error and throws at
+ * construction rather than silently shadowing.
+ */
+export declare function createCredentialProviderRegistry(providers: readonly CredentialProvider[]): CredentialProviderRegistry;
+/**
+ * The minimal call signature the shaped handle needs from `fetch`. The global
+ * `fetch` satisfies it; a test stub can too, without implementing the extra
+ * members (`preconnect`) the full `fetch` type carries.
+ */
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** Options for the built-in HTTP provider. */
+export interface HttpCredentialProviderOptions {
+    /**
+     * The `fetch` the shaped handle delegates to once the request is
+     * origin-checked and the auth header is injected. Defaults to the global
+     * `fetch`; injectable so origin-pinning can be exercised without a network.
+     */
+    fetch?: FetchLike;
+}
+/**
+ * The built-in HTTP credential provider. It shapes an `HttpMediatedCredential`:
+ * an authed `fetch` pinned to the credential's provider origin, injecting the
+ * current secret as a bearer token per request. The material is read fresh on
+ * every call, so a rotation that updates the underlying cell is picked up
+ * without rebuilding the handle.
+ *
+ * Origin pinning is load-bearing security: the handle authenticates only the
+ * initial, origin-checked request and never follows redirects. A request whose
+ * resolved origin is not the pinned one is refused, and a server 3xx is
+ * returned to the caller unfollowed (`redirect: "manual"`), so the bearer is
+ * never sent to any origin but the pinned one. Transparent redirect-following
+ * is intentionally not provided: a tool re-issues a same-origin redirect target
+ * through the handle (a cross-origin one is refused). This keeps token safety
+ * in the handle rather than resting on the injected `fetch`'s redirect
+ * behavior.
+ *
+ * Bearer is the only auth scheme today; providers that authenticate differently
+ * (a `token` scheme, an `x-api-key` header) are separate plugins, not a branch
+ * here.
+ */
+export declare function createHttpCredentialProvider(opts?: HttpCredentialProviderOptions): CredentialProvider;
+/**
+ * The built-in credential providers every host registers. A single `http`
+ * provider today; a host composes additional providers by extending the list
+ * passed to `createCredentialProviderRegistry`.
+ */
+export declare function builtinCredentialProviders(): CredentialProvider[];

package/dist/credential-providers.js

@@ -0,0 +1,123 @@
+// Credential provider plugins: the seam that shapes a resolved provider-backed
+// credential into a mediated handle a consumer can use. A provider owns HOW the
+// handle authenticates (an authed `fetch`, a future key-file + socket); it is
+// given a material source and never acquires material or decides authorization
+// -- both happen upstream, at the delivery boundary, before a provider is
+// consulted.
+//
+// The registry mirrors @intx/inference's AdapterRegistry: a Map-backed lookup
+// keyed by provider identifier, prototype-pollution-safe (a Map never consults
+// Object.prototype, so an untrusted key like "toString" resolves to the loud
+// unknown-provider error rather than an inherited member), throw-on-missing.
+/**
+ * Build a registry from a list of providers. The list is copied into a private
+ * `Map`, so callers cannot mutate the set after construction and lookups never
+ * reach `Object.prototype`. A duplicate key is a wiring error and throws at
+ * construction rather than silently shadowing.
+ */
+export function createCredentialProviderRegistry(providers) {
+    const byKey = new Map();
+    for (const provider of providers) {
+        if (byKey.has(provider.key)) {
+            throw new Error(`Duplicate credential provider key: ${provider.key}`);
+        }
+        byKey.set(provider.key, provider);
+    }
+    return {
+        has(key) {
+            return byKey.has(key);
+        },
+        resolve(key) {
+            const provider = byKey.get(key);
+            if (provider === undefined) {
+                throw new Error(`Unknown credential provider: ${key}`);
+            }
+            return provider;
+        },
+    };
+}
+/**
+ * The built-in HTTP credential provider. It shapes an `HttpMediatedCredential`:
+ * an authed `fetch` pinned to the credential's provider origin, injecting the
+ * current secret as a bearer token per request. The material is read fresh on
+ * every call, so a rotation that updates the underlying cell is picked up
+ * without rebuilding the handle.
+ *
+ * Origin pinning is load-bearing security: the handle authenticates only the
+ * initial, origin-checked request and never follows redirects. A request whose
+ * resolved origin is not the pinned one is refused, and a server 3xx is
+ * returned to the caller unfollowed (`redirect: "manual"`), so the bearer is
+ * never sent to any origin but the pinned one. Transparent redirect-following
+ * is intentionally not provided: a tool re-issues a same-origin redirect target
+ * through the handle (a cross-origin one is refused). This keeps token safety
+ * in the handle rather than resting on the injected `fetch`'s redirect
+ * behavior.
+ *
+ * Bearer is the only auth scheme today; providers that authenticate differently
+ * (a `token` scheme, an `x-api-key` header) are separate plugins, not a branch
+ * here.
+ */
+export function createHttpCredentialProvider(opts) {
+    const fetchImpl = opts?.fetch ?? globalThis.fetch;
+    return {
+        key: "http",
+        shape(context) {
+            const pinnedOrigin = new URL(context.origin).origin;
+            return {
+                kind: "http",
+                async fetch(input, init) {
+                    const target = resolveTargetUrl(input, pinnedOrigin);
+                    if (target.origin !== pinnedOrigin) {
+                        throw new Error(`http credential is pinned to ${pinnedOrigin}; refusing cross-origin request to ${target.origin}`);
+                    }
+                    // Read the secret fresh on every call so a rotation of the underlying
+                    // material cell reaches this handle without a rebuild.
+                    const { secret } = context.readCurrentMaterial();
+                    // redirect:"manual" is dictated by the handle, never inherited from
+                    // caller input. The origin check guards only the INITIAL url, so
+                    // following a server 3xx to a foreign origin would carry the bearer
+                    // off the pinned host. Instead the 3xx is returned to the caller
+                    // unfollowed: a same-origin target is re-issued through the handle
+                    // (which re-pins and re-auths); a cross-origin one is refused above.
+                    if (input instanceof Request) {
+                        // Re-issue the caller's request (method, body preserved) with the
+                        // auth header added and the redirect mode forced; its url was
+                        // origin-checked above.
+                        const headers = new Headers(input.headers);
+                        headers.set("authorization", `Bearer ${secret}`);
+                        return fetchImpl(new Request(input, { headers, redirect: "manual" }));
+                    }
+                    const headers = new Headers(init?.headers);
+                    headers.set("authorization", `Bearer ${secret}`);
+                    return fetchImpl(target, { ...init, headers, redirect: "manual" });
+                },
+                dispose() {
+                    // An http handle allocates no resources; nothing to release.
+                },
+            };
+        },
+    };
+}
+/**
+ * The built-in credential providers every host registers. A single `http`
+ * provider today; a host composes additional providers by extending the list
+ * passed to `createCredentialProviderRegistry`.
+ */
+export function builtinCredentialProviders() {
+    return [createHttpCredentialProvider()];
+}
+/**
+ * Resolve the URL a request targets. A relative string resolves against the
+ * pinned origin (so a tool can call `/repos`); an absolute string or URL keeps
+ * its own origin (and is refused by the caller if it differs); a `Request`
+ * carries an absolute URL already.
+ */
+function resolveTargetUrl(input, pinnedOrigin) {
+    if (typeof input === "string") {
+        return new URL(input, pinnedOrigin);
+    }
+    if (input instanceof URL) {
+        return input;
+    }
+    return new URL(input.url);
+}

package/dist/harness.d.ts

@@ -1,4 +1,4 @@
-import { type Agent, type AgentDefinition, type AnnotatedToolFactory, type BaseEnv, type ToolBundle } from "@intx/agent";
+import { type Agent, type AgentDefinition, type AnnotatedToolFactory, type BaseEnv, type ToolBundle, type ToolDeclaration } from "@intx/agent";
 import type { BlobReader, ConnectorThreadState, ContextStore, InboundMessage, InferenceSource, MessageTransport } from "@intx/types/runtime";
 import { createConnectorRouter } from "./connector-router.js";
 /**
@@ -167,8 +167,14 @@ export declare function createWrappedStorageOverrides(baseStorage: ContextStore,
  * the "what does the harness need vs. what does the tool runner
  * need" partition onto the caller, which is exactly the partition
  * this helper exists to hide.
+ *
+ * `definitions` is the static declaration `defineTool` requires: the
+ * tool names this factory contributes, enumerable without invoking the
+ * wrapper. The caller supplies it because the wrapper binds `transport`
+ * from env and cannot run at declaration time; the caller already holds
+ * the mail-tool runner whose `definitions` name the same tools.
  */
-export declare function defineMailTools(wrapper: MailToolWrapper): AnnotatedToolFactory<MailEnv>;
+export declare function defineMailTools(wrapper: MailToolWrapper, definitions: readonly ToolDeclaration[]): AnnotatedToolFactory<MailEnv>;
 /**
  * Construct a composition-layer agent: the underlying agent wrapped
  * with connector-state-aware storage, transport subscription, INBOX

package/dist/harness.js

@@ -146,11 +146,18 @@ export function createWrappedStorageOverrides(baseStorage, connectorRouter, isIn
  * the "what does the harness need vs. what does the tool runner
  * need" partition onto the caller, which is exactly the partition
  * this helper exists to hide.
+ *
+ * `definitions` is the static declaration `defineTool` requires: the
+ * tool names this factory contributes, enumerable without invoking the
+ * wrapper. The caller supplies it because the wrapper binds `transport`
+ * from env and cannot run at declaration time; the caller already holds
+ * the mail-tool runner whose `definitions` name the same tools.
  */
-export function defineMailTools(wrapper) {
+export function defineMailTools(wrapper, definitions) {
     return defineTool({
         id: "@intx/harness/mail",
         requires: ["transport", "address"],
+        definitions,
         factory: (env) => {
             const bundle = wrapper(env.transport);
             return {

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 export { createHarness, defineMailTools, type Harness, type MailEnv, type MailToolWrapper, } from "./harness.js";
 export { createHarnessRuntimeCapabilities } from "./runtime-capabilities.js";
 export type { HarnessRuntimeCapabilitiesOptions } from "./runtime-capabilities.js";
+export { createCredentialProviderRegistry, createHttpCredentialProvider, builtinCredentialProviders, } from "./credential-providers.js";
+export type { CredentialProviderRegistry, FetchLike, HttpCredentialProviderOptions, } from "./credential-providers.js";
+export { createCredentialCapability, reconcileDeclaredCredentials, } from "./credential-capability.js";
+export type { CredentialCapabilityDeps, HostCredentialCapability, ResolvedCredentialBinding, } from "./credential-capability.js";
 export { createConnectorRouter, NoActiveConnectorThreadError, } from "./connector-router.js";
 export type { ConnectorRouter, ConnectorReplyParts, ConnectorRouterOptions, RouteDecision, } from "./connector-router.js";

package/dist/index.js

@@ -1,3 +1,5 @@
 export { createHarness, defineMailTools, } from "./harness.js";
 export { createHarnessRuntimeCapabilities } from "./runtime-capabilities.js";
+export { createCredentialProviderRegistry, createHttpCredentialProvider, builtinCredentialProviders, } from "./credential-providers.js";
+export { createCredentialCapability, reconcileDeclaredCredentials, } from "./credential-capability.js";
 export { createConnectorRouter, NoActiveConnectorThreadError, } from "./connector-router.js";

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@intx/harness",
-  "version": "0.2.2",
+  "description": "Mail-transport composition layer over @intx/agent adding INBOX watch and connector routing",
+  "version": "0.3.0",
   "license": "LGPL-2.1-only",
   "type": "module",
   "exports": {
@@ -11,14 +12,15 @@
     }
   },
   "dependencies": {
-    "@intx/agent": "0.2.2",
-    "@intx/log": "0.2.2",
-    "@intx/types": "0.2.2"
+    "@intx/agent": "0.3.0",
+    "@intx/authz": "0.3.0",
+    "@intx/log": "0.3.0",
+    "@intx/types": "0.3.0"
   },
   "devDependencies": {
-    "@intx/inference-testing": "0.2.2",
-    "@intx/mime": "0.2.2",
-    "@intx/storage-isogit": "0.2.2",
+    "@intx/inference-testing": "0.3.0",
+    "@intx/mime": "0.3.0",
+    "@intx/storage-isogit": "0.3.0",
     "arktype": "^2.1.29"
   },
   "files": [