@zackbart/connecta 0.37.1 → 0.39.0

package/dist/connectors/resource-uri.js

@@ -26,10 +26,6 @@ export function resourceUriMatchesTemplates(uri, templates, note = () => { }) {
     }
     return matched ? { matched } : { matched, ...(refusal ? { refusal } : {}) };
 }
-export function resourceUriMatchesTemplate(uri, template) {
-    const parsed = parse(template);
-    return typeof parsed === "object" && matches(uri, parsed);
-}
 function parse(template) {
     if (template.length > MAX_URI_LENGTH)
         return;

package/dist/credential-contract.d.ts

@@ -10,6 +10,12 @@ export interface CredentialMetadata {
     /** Backward-compatible metadata for the reserved single credential field. */
     lastFour?: string;
     updatedAt: string;
+    /**
+     * Opaque and unique to the save this metadata describes. Credential
+     * verification is recorded only against it, so a vault that omits it
+     * stores credentials that are never shown as verified.
+     */
+    revision?: string;
     /** Per-field masked metadata for named multi-value credentials. */
     fields?: Record<string, CredentialFieldMetadata>;
 }
@@ -20,6 +26,15 @@ export interface CredentialVault {
     set(connectorId: string, value: string, updatedBy: string, owner?: string): Promise<CredentialMetadata>;
     setAll(connectorId: string, values: ConnectorCredentialValues, updatedBy: string, owner?: string): Promise<CredentialMetadata>;
     delete(connectorId: string, owner?: string): Promise<void>;
+    /**
+     * The values and metadata of one save, read together so neither can come
+     * from a later save. Without it, a Test of the stored credential records
+     * no verification.
+     */
+    snapshot?(connectorId: string, owner?: string): Promise<{
+        values: ConnectorCredentialValues;
+        metadata: CredentialMetadata;
+    } | null>;
     /**
      * Encrypt downstream OAuth state (tokens, a registered client, a PKCE
      * verifier) before it enters storage. `purpose` is the storage key the value
@@ -37,6 +52,14 @@ export interface CredentialVault {
      * exposes the vault or this key through a connector context or guest API.
      */
     requestStateKey?(): Promise<Uint8Array>;
+    /**
+     * Host-only HMAC-SHA-256 signing key for stored remote catalog,
+     * negotiation-verdict and connector-health keys, so those partitions are
+     * deployment-keyed. Must be stable across the deployment's processes,
+     * purpose-specific, and never stored. Without it, those keys use a random
+     * per-process key, and such entries are reused only within one process.
+     */
+    storageDigestKey?(): Promise<CryptoKey>;
     /** Reverse `seal` for the same connector, purpose, and owner; rejects otherwise. */
     open?(connectorId: string, purpose: string, sealed: string, owner?: string): Promise<string>;
 }

package/dist/credential-reads.js

@@ -0,0 +1,17 @@
+const readers = new WeakMap();
+/** `canonical` is the base class's own prototype methods, never the instance's. */
+export function registerCredentialReads(vault, canonical, memo) {
+    readers.set(vault, { canonical, memo });
+}
+/** A `fresh` reader always reads storage and records what it saw. */
+export function credentialReads(vault, reads, fresh = false) {
+    const reader = readers.get(vault);
+    return {
+        getAll: (connectorId, owner) => reader && vault.getAll === reader.canonical.getAll
+            ? reader.memo.getAll(connectorId, owner, reads, fresh)
+            : vault.getAll(connectorId, owner),
+        metadata: (connectorId, owner) => reader && vault.metadata === reader.canonical.metadata
+            ? reader.memo.metadata(connectorId, owner, reads, fresh)
+            : vault.metadata(connectorId, owner),
+    };
+}

package/dist/credential-verification.js

@@ -0,0 +1,53 @@
+// The last verification of a connector's operator-managed credential: a typed,
+// payload-free observation stored per connector and owner (the connector's
+// `ctx.storage` is already partitioned by both). Credential tests and saves
+// write it; the operator page only reads it (INV-10).
+import { classifyCallError } from "./errors.js";
+import { verificationKeys } from "./storage/keys.js";
+const FAILURES = ["rejected", "scope", "unreachable", "timeout", "failed"];
+const OUTCOMES = ["ok", "unverified", "rejected", "scope", "unreachable", "timeout", "failed"];
+/** Each typed code that names a class; every other code is `failed`. */
+const CLASS_OF = {
+    auth_required: "rejected",
+    downstream_oauth_required: "rejected",
+    provider_permission_denied: "scope",
+    timeout: "timeout",
+    unavailable: "unreachable",
+    rate_limited: "unreachable",
+};
+/** A thrown failure's class, read from its typed code alone, never its text. */
+export const credentialFailureClass = (error) => CLASS_OF[classifyCallError(error).code] ?? "failed";
+/** A hook's answer as an outcome. Only its typed fields count; `message` never does. */
+export const credentialTestOutcome = (result) => result?.ok === true ? "ok" : FAILURES.includes(result?.failure) ? result.failure : "failed";
+/** A checked copy, or undefined: nothing here trusts stored bytes. */
+function checkedVerification(value) {
+    const { outcome, observedAt } = (value ?? {});
+    return OUTCOMES.includes(outcome) &&
+        typeof observedAt === "string" &&
+        observedAt.length < 64 &&
+        !Number.isNaN(Date.parse(observedAt))
+        ? { outcome: outcome, observedAt }
+        : undefined;
+}
+/**
+ * The stored observation, or undefined when there is none or it cannot be
+ * read. With `credential`, only one made about that vault credential (its
+ * `updatedAt`) counts: a replacement saved since is unverified.
+ */
+export async function readVerification(storage, credential) {
+    try {
+        const stored = JSON.parse((await storage.get(verificationKeys.record)) ?? "null");
+        return credential === undefined || stored?.credential === credential ? checkedVerification(stored) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Record an outcome, bound to the vault credential's `updatedAt` when it is about one; `null` removes the record. */
+export async function writeVerification(storage, outcome, credential) {
+    if (!outcome)
+        return void (await storage.delete(verificationKeys.record));
+    const record = { outcome, observedAt: new Date().toISOString() };
+    await storage.set(verificationKeys.record, JSON.stringify({ ...record, credential }));
+    return record;
+}

package/dist/credentials.d.ts

@@ -11,15 +11,22 @@ export declare class CredentialVault implements Vault {
     private readonly key;
     private readonly handoffKey;
     private readonly retryKey;
+    private readonly digestKey;
     constructor(storage: KVStorage, encryptionKey: string);
     signOAuthHandoff(payload: string): Promise<string>;
     requestStateKey(): Promise<Uint8Array>;
+    storageDigestKey(): Promise<CryptoKey>;
     verifyOAuthHandoff(payload: string, signature: string): Promise<boolean>;
     private additionalData;
     private read;
     get(connectorId: string, field?: string, owner?: string): Promise<string | null>;
     getAll(connectorId: string, owner?: string): Promise<ConnectorCredentialValues | null>;
     metadata(connectorId: string, owner?: string): Promise<CredentialMetadata | null>;
+    /** The values and metadata of one save, from a single envelope read. */
+    snapshot(connectorId: string, owner?: string): Promise<{
+        values: ConnectorCredentialValues;
+        metadata: CredentialMetadata;
+    } | null>;
     set(connectorId: string, value: string, updatedBy: string, owner?: string): Promise<CredentialMetadata>;
     setAll(connectorId: string, values: ConnectorCredentialValues, updatedBy: string, owner?: string): Promise<CredentialMetadata>;
     delete(connectorId: string, owner?: string): Promise<void>;

package/dist/credentials.js

@@ -1,6 +1,7 @@
 import { advanceCatalogRevision } from "./catalog-revision.js";
-import { deriveOAuthHandoffKey, deriveRequestStateKey } from "./oauth-sealing.js";
+import { deriveOAuthHandoffKey, deriveRequestStateKey, deriveStorageDigestKey } from "./oauth-sealing.js";
 import { credentialKeys } from "./storage/keys.js";
+import { registerCredentialReads } from "./credential-reads.js";
 const KEY_BYTES = 32;
 const IV_BYTES = 12;
 const MAX_CREDENTIAL_BYTES = 16_384;
@@ -50,7 +51,7 @@ function parseEnvelope(raw) {
         throw new Error("Stored credential is invalid or corrupted");
     }
 }
-function parsePlaintext(raw) {
+function parsePlaintext(raw, iv) {
     try {
         const parsed = JSON.parse(raw);
         const values = typeof parsed.value === "string" ? { value: parsed.value } : parsed.values;
@@ -66,6 +67,7 @@ function parsePlaintext(raw) {
             values: { ...values },
             updatedAt: parsed.updatedAt,
             updatedBy: parsed.updatedBy,
+            revision: typeof parsed.revision === "string" ? parsed.revision : iv,
         };
     }
     catch {
@@ -91,6 +93,28 @@ function validateValues(values) {
     }
     return normalized;
 }
+function metadataOf(credential) {
+    if (!credential)
+        return null;
+    const fields = Object.fromEntries(Object.entries(credential.values).map(([field, value]) => [
+        field,
+        {
+            configured: true,
+            // Only reveal the tail on values comfortably longer than four chars;
+            // for a short secret those four would be half of it.
+            ...(value.length >= 12 ? { lastFour: value.slice(-4) } : {}),
+            updatedAt: credential.updatedAt,
+        },
+    ]));
+    const single = fields.value;
+    return {
+        configured: true,
+        ...(single?.lastFour ? { lastFour: single.lastFour } : {}),
+        updatedAt: credential.updatedAt,
+        revision: credential.revision,
+        fields,
+    };
+}
 /**
  * Encrypted, connector-scoped credential vault over the deployment's existing
  * KVStorage. Only ciphertext enters storage; the AES-GCM key remains an environment
@@ -102,6 +126,7 @@ export class CredentialVault {
     key;
     handoffKey;
     retryKey;
+    digestKey;
     constructor(storage, encryptionKey) {
         this.storage = storage;
         const raw = base64ToBytes(encryptionKey.trim());
@@ -110,7 +135,16 @@ export class CredentialVault {
         }
         this.handoffKey = deriveOAuthHandoffKey(raw);
         this.retryKey = deriveRequestStateKey(raw);
+        this.digestKey = deriveStorageDigestKey(raw);
         this.key = crypto.subtle.importKey("raw", raw, { name: "AES-GCM" }, false, ["encrypt", "decrypt"]);
+        // The base class's original methods, so an override is never replaced.
+        registerCredentialReads(this, canonicalReads, {
+            getAll: async (connectorId, owner, reads, fresh) => {
+                const credential = await this.read(connectorId, owner, { reads, fresh });
+                return credential ? { ...credential.values } : null;
+            },
+            metadata: async (connectorId, owner, reads, fresh) => metadataOf(await this.read(connectorId, owner, { reads, fresh })),
+        });
     }
     async signOAuthHandoff(payload) {
         return bytesToBase64(new Uint8Array(await crypto.subtle.sign("HMAC", await this.handoffKey, encoder.encode(payload))));
@@ -118,6 +152,9 @@ export class CredentialVault {
     async requestStateKey() {
         return new Uint8Array(await this.retryKey);
     }
+    storageDigestKey() {
+        return this.digestKey;
+    }
     async verifyOAuthHandoff(payload, signature) {
         try {
             return await crypto.subtle.verify("HMAC", await this.handoffKey, base64ToBytes(signature), encoder.encode(payload));
@@ -129,8 +166,11 @@ export class CredentialVault {
     additionalData(connectorId, owner) {
         return encoder.encode(owner ? `connecta:credential:principal:${owner}:${connectorId}:v1` : `connecta:credential:${connectorId}:v1`);
     }
-    async read(connectorId, owner) {
-        const raw = await this.storage.get(storageKey(connectorId, owner));
+    async read(connectorId, owner, memo) {
+        const key = storageKey(connectorId, owner);
+        const raw = memo
+            ? await memo.reads.readPromise(this.storage, key, () => this.storage.get(key), memo.fresh)
+            : await this.storage.get(key);
         if (!raw)
             return null;
         const envelope = parseEnvelope(raw);
@@ -140,7 +180,7 @@ export class CredentialVault {
                 iv: base64ToBytes(envelope.iv),
                 additionalData: this.additionalData(connectorId, owner),
             }, await this.key, base64ToBytes(envelope.ciphertext));
-            return parsePlaintext(decoder.decode(plaintext));
+            return parsePlaintext(decoder.decode(plaintext), envelope.iv);
         }
         catch {
             throw new Error("Stored credential could not be decrypted");
@@ -155,26 +195,12 @@ export class CredentialVault {
         return credential ? { ...credential.values } : null;
     }
     async metadata(connectorId, owner) {
+        return metadataOf(await this.read(connectorId, owner));
+    }
+    /** The values and metadata of one save, from a single envelope read. */
+    async snapshot(connectorId, owner) {
         const credential = await this.read(connectorId, owner);
-        if (!credential)
-            return null;
-        const fields = Object.fromEntries(Object.entries(credential.values).map(([field, value]) => [
-            field,
-            {
-                configured: true,
-                // Only reveal the tail on values comfortably longer than four chars;
-                // for a short secret those four would be half of it.
-                ...(value.length >= 12 ? { lastFour: value.slice(-4) } : {}),
-                updatedAt: credential.updatedAt,
-            },
-        ]));
-        const single = fields.value;
-        return {
-            configured: true,
-            ...(single?.lastFour ? { lastFour: single.lastFour } : {}),
-            updatedAt: credential.updatedAt,
-            fields,
-        };
+        return credential && { values: { ...credential.values }, metadata: metadataOf(credential) };
     }
     async set(connectorId, value, updatedBy, owner) {
         // `await` (not a bare promise return) so a validation throw inside setAll
@@ -188,6 +214,7 @@ export class CredentialVault {
             values: normalized,
             updatedAt: new Date().toISOString(),
             updatedBy,
+            revision: crypto.randomUUID(),
         };
         const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
         const ciphertext = await crypto.subtle.encrypt({
@@ -203,7 +230,9 @@ export class CredentialVault {
         };
         await this.storage.set(storageKey(connectorId, owner), JSON.stringify(envelope));
         advanceCatalogRevision(this);
-        return (await this.metadata(connectorId, owner));
+        // What this write stored, never a re-read: a concurrent save may already
+        // have replaced it, and its revision must not be reported as this one's.
+        return metadataOf(plaintext);
     }
     async delete(connectorId, owner) {
         await this.storage.delete(storageKey(connectorId, owner));
@@ -238,6 +267,12 @@ export class CredentialVault {
         }
     }
 }
+// Captured once at definition: a later subclass, instance or prototype
+// override of either method is always called itself (credential-reads.ts).
+const canonicalReads = {
+    getAll: CredentialVault.prototype.getAll,
+    metadata: CredentialVault.prototype.metadata,
+};
 export function encryptedCredentialVault(storage, encryptionKey) {
     return new CredentialVault(storage, encryptionKey);
 }

package/dist/d1.d.ts

@@ -38,93 +38,4 @@ export declare function d1Storage(db: D1DatabaseBinding): KVStorage;
  * write prunes a bounded batch of rows older than `retentionDays`.
  */
 export declare function d1ActivityStore(db: D1DatabaseBinding, options?: D1ActivityOptions): ActivityStore;
-/**
- * The part of a Workers KV binding `copyKvToD1` reads. Structural, like
- * `D1DatabaseBinding`; a Worker's `KVNamespace` satisfies it.
- */
-export interface KVNamespaceBinding {
-    list(options?: {
-        limit?: number;
-        cursor?: string | null;
-    }): Promise<{
-        keys: readonly {
-            name: string;
-            expiration?: number;
-        }[];
-        list_complete: boolean;
-        cursor?: string;
-    }>;
-    get(key: string, type: "text"): Promise<string | null>;
-}
-export interface KvToD1CopyOptions {
-    /** The source KV namespace id. Resume tokens are bound to this identity. */
-    source: string;
-    /** Resume against the same source and database within seven days. */
-    cursor?: string;
-    /** Explicit families whose conflicting D1 rows the operator judged stale. */
-    overwriteFamilies?: readonly string[];
-    /** Compare value hashes and absolute expiries without copying entries. */
-    verify?: boolean;
-    /** Override the cutover guard only after assessing stale KV state. */
-    allowStale?: boolean;
-    /** Keys read per call. Default 500; use a smaller budget for large rows. */
-    maxKeys?: number;
-}
-/** What a copy did with one family's keys. */
-export interface KvToD1Counts {
-    /** Written where D1 held no live entry. */
-    copied: number;
-    /** D1 already held the same value. */
-    unchanged: number;
-    /** D1 held a different value or expiry and kept it. */
-    conflicts: number;
-    /** D1 held a different value or expiry, replaced under `overwriteFamilies`. */
-    overwritten: number;
-    /** Expired or deleted in Workers KV before it could be read. */
-    expired: number;
-    /** A key/value/row D1 cannot hold, left in Workers KV. */
-    invalid: number;
-    /** Exact value hash and expiry match during a verification pass. */
-    verified: number;
-    /** Missing or different value/expiry during a verification pass. */
-    mismatches: number;
-}
-export interface KvToD1CopyResult {
-    /** True once the whole namespace has been read. */
-    done: boolean;
-    /**
-     * Pass back as `options.cursor` to continue; absent when `done`. A random
-     * token: the Workers KV cursor it stands for stays in D1, because that
-     * cursor can spell the last key listed.
-     */
-    cursor?: string;
-    /**
-     * Counts by key family (`src/storage/keys.ts`), plus `connector-owned` and
-     * `unclassified`. Never a key or a value.
-     */
-    families: Record<string, KvToD1Counts>;
-}
-/**
- * A copy that stopped. The message is fixed wording that names a family at
- * most, never a key or value, and the binding's own error is not attached:
- * KV and D1 errors can quote either. Entries before `cursor` are copied;
- * rerunning from it is safe while the maintenance window still holds.
- */
-export declare class KvToD1CopyError extends Error {
-    /** Resume point; absent means start over, which is also safe. */
-    readonly cursor: string | undefined;
-    readonly name = "KvToD1CopyError";
-    constructor(message: string, 
-    /** Resume point; absent means start over, which is also safe. */
-    cursor: string | undefined);
-}
-/** Mark cutover before reopening traffic. The marker stays in D1 permanently. */
-export declare function markKvToD1Live(db: D1DatabaseBinding, source: string): Promise<void>;
-/**
- * Copy live KV entries verbatim while all writers and traffic are stopped.
- * A live D1 row is kept unless its family is explicitly allowed to overwrite.
- * `verify` reads hashes and absolute expiries without changing copied entries.
- * Results contain counts only. Resume tokens are source-bound atomic claims.
- */
-export declare function copyKvToD1(kv: KVNamespaceBinding, db: D1DatabaseBinding, options: KvToD1CopyOptions): Promise<KvToD1CopyResult>;
 export {};

package/dist/d1.js

@@ -3,12 +3,8 @@
 // One D1 database holds everything: `d1Storage(db)` is the deployment's
 // `KVStorage`, and `d1ActivityStore(db)` its activity history. Both create
 // their tables on first use, so binding the database is the whole setup.
-// `copyKvToD1` moves a 0.28 deployment's Workers KV state into it once.
-import { runEdge } from "./runtime/run.js";
 import { d1Driver } from "./storage/d1-driver.js";
-import { copyKvToD1Effect, markKvToD1LiveEffect } from "./storage/d1-copy.js";
 import { sqlActivityStore, sqlStorage } from "./storage/sql.js";
-import { keepErrorName } from "./redaction-identity.js";
 /**
  * `KVStorage` over a D1 database, with the atomic `compareAndSet` every
  * subsystem relies on. The `connecta_kv` table is created on first use; a
@@ -25,33 +21,3 @@ export function d1Storage(db) {
 export function d1ActivityStore(db, options) {
     return sqlActivityStore(d1Driver(db), "d1", options);
 }
-/**
- * A copy that stopped. The message is fixed wording that names a family at
- * most, never a key or value, and the binding's own error is not attached:
- * KV and D1 errors can quote either. Entries before `cursor` are copied;
- * rerunning from it is safe while the maintenance window still holds.
- */
-export class KvToD1CopyError extends Error {
-    cursor;
-    name = "KvToD1CopyError";
-    constructor(message, 
-    /** Resume point; absent means start over, which is also safe. */
-    cursor) {
-        super(message);
-        this.cursor = cursor;
-    }
-}
-keepErrorName(KvToD1CopyError, "KvToD1CopyError");
-/** Mark cutover before reopening traffic. The marker stays in D1 permanently. */
-export function markKvToD1Live(db, source) {
-    return runEdge(markKvToD1LiveEffect(db, source));
-}
-/**
- * Copy live KV entries verbatim while all writers and traffic are stopped.
- * A live D1 row is kept unless its family is explicitly allowed to overwrite.
- * `verify` reads hashes and absolute expiries without changing copied entries.
- * Results contain counts only. Resume tokens are source-bound atomic claims.
- */
-export function copyKvToD1(kv, db, options) {
-    return runEdge(copyKvToD1Effect(kv, db, options));
-}

package/dist/describe-config.d.ts

@@ -1,6 +1,6 @@
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import type { ConnectaConfig, ResolvedConfig } from "./config.js";
-import type { ResolvedPool } from "./membership.js";
+import { type ResolvedPool } from "./membership.js";
 import type { ConnectorAuthDescription, ConnectorDescription, ConnectorToolDescription, DescribedEndpoint, IdentityReference } from "./types.js";
 /** Where a limit's value came from. */
 export type ConfigValueSource = "default" | "config";
@@ -100,11 +100,21 @@ export interface ConnectaConfigDescription {
     };
     /** Whether the default /mcp endpoint refuses every write, and exact classification overrides from deployment code. */
     readOnly: boolean;
-    /** The principals plain `/mcp` admits, resolved, in declaration order. Empty on an open deployment. */
+    /**
+     * The people plain `/mcp` serves the whole catalog, resolved, in declaration
+     * order. Empty on an open deployment. Every other person reaches plain
+     * `/mcp` only through exactly one pool's `members`, which it then serves.
+     */
     maintainers: Array<{
         namespace: string;
         id: string;
     }>;
+    /** Non-maintainer people listed in several pools, whom plain `/mcp` refuses. */
+    peopleInSeveralPools: Array<{
+        namespace: string;
+        id: string;
+        pools: string[];
+    }>;
     classification: Record<string, Record<string, "read" | "write" | "hidden">>;
     /** Inbound auth providers in the order they are tried. */
     auth: Array<{

package/dist/describe-config.js

@@ -15,6 +15,7 @@ import { resolveBranding } from "./branding.js";
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import { describedEndpoint, describedHref, describedOrigin, describedTools, describedUrl } from "./described.js";
 import { connectorGuideRequired, connectorGuideSummary } from "./skills.js";
+import { peopleInSeveralPools } from "./membership.js";
 import { CONNECTA_VERSION } from "./version.js";
 const str = (value) => (typeof value === "string" ? value : undefined);
 const num = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
@@ -235,6 +236,7 @@ export function describeConfig(input) {
         },
         readOnly: config.readOnly,
         maintainers: input.maintainers.map(({ namespace, id }) => ({ namespace: String(namespace), id: String(id) })),
+        peopleInSeveralPools: peopleInSeveralPools(input.pools, input.maintainers),
         classification: structuredClone(config.classification ?? {}),
         auth: config.auth.map((provider) => ({
             kind: String(provider.kind),