@zackbart/connecta 0.24.3 → 0.25.0

package/dist/credential-contract.d.ts

@@ -20,5 +20,14 @@ 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>;
+    /**
+     * Encrypt downstream OAuth state (tokens, a registered client, a PKCE
+     * verifier) before it enters storage. `purpose` is the storage key the value
+     * is written under, so the result is bound to one connector, owner, and key.
+     * Without both `seal` and `open`, that state is stored as plaintext.
+     */
+    seal?(connectorId: string, purpose: string, plaintext: string, owner?: string): Promise<string>;
+    /** Reverse `seal` for the same connector, purpose, and owner; rejects otherwise. */
+    open?(connectorId: string, purpose: string, sealed: string, owner?: string): Promise<string>;
 }
 export {};

package/dist/credential-rules.js

@@ -3,7 +3,7 @@ export const STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR = "Stored credential fields
 /**
  * Compare a connector's current declaration with the keys in its stored
  * credential. Values are deliberately ignored: callers may pass decrypted
- * values or `/credentials`' masked field metadata and get the same answer.
+ * values or the operator UI's masked credential field metadata and get the same answer.
  *
  * The test is CONTAINMENT, not equality: the stored key set is compatible when
  * it holds every field currently declared — the reserved `value` key for a
@@ -65,7 +65,7 @@ export function describeUndeclaredCredentialFields(fields) {
 }
 /**
  * The one rule deciding whether a connector's credential can be tested — read
- * by /credentials' `testable` flag, by `POST /ui/credentials/<id>/test` when
+ * by the operator UI's credential `testable` flag, by `POST /ui/credentials/<id>/test` when
  * it picks a hook, and by the construction-time mismatch warning, so those
  * three cannot drift apart.
  *

package/dist/credentials.d.ts

@@ -3,7 +3,8 @@ import type { ConnectorCredentialValues, KVStorage } from "./types.js";
 /**
  * Encrypted, connector-scoped credential vault over the deployment's existing
  * KVStorage. Only ciphertext enters KV; the AES-GCM key remains an environment
- * secret outside the store.
+ * secret outside the store. The same key seals downstream OAuth state, which
+ * the OAuth provider stores itself.
  */
 export declare class CredentialVault implements Vault {
     private readonly storage;
@@ -17,5 +18,9 @@ export declare class CredentialVault implements Vault {
     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>;
+    /** Encrypt downstream OAuth state under the vault key; nothing is stored. */
+    seal(connectorId: string, purpose: string, plaintext: string, owner?: string): Promise<string>;
+    /** Decrypt what `seal` produced for this connector, purpose, and owner. */
+    open(connectorId: string, purpose: string, sealed: string, owner?: string): Promise<string>;
 }
 export declare function encryptedCredentialVault(storage: KVStorage, encryptionKey: string): Vault;

package/dist/credentials.js

@@ -3,6 +3,16 @@ const IV_BYTES = 12;
 const MAX_CREDENTIAL_BYTES = 16_384;
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
+/** Version tag of the compact `seal` output: `v1.<iv>.<ciphertext>`. */
+const SEALED_VERSION = "v1";
+/**
+ * Binds sealed OAuth state to its connector, owner, and physical storage key
+ * (which carries the authorization epoch), so ciphertext copied anywhere else
+ * does not open. Connector ids cannot contain `|`, and the owner is a hash.
+ */
+function oauthStateAdditionalData(connectorId, purpose, owner) {
+    return encoder.encode(`connecta:oauth-state:v1|${connectorId}|${owner ?? ""}|${purpose}`);
+}
 function storageKey(connectorId, owner) {
     return owner
         ? `principal:${owner}:conn:${connectorId}:credential:v1`
@@ -20,7 +30,7 @@ function base64ToBytes(value) {
         binary = atob(value);
     }
     catch {
-        throw new Error("credentials.encryptionKey must be a base64-encoded 32-byte key");
+        throw new Error("The credential vault encryption key must be a base64-encoded 32-byte key");
     }
     return Uint8Array.from(binary, (char) => char.charCodeAt(0));
 }
@@ -87,7 +97,8 @@ function validateValues(values) {
 /**
  * Encrypted, connector-scoped credential vault over the deployment's existing
  * KVStorage. Only ciphertext enters KV; the AES-GCM key remains an environment
- * secret outside the store.
+ * secret outside the store. The same key seals downstream OAuth state, which
+ * the OAuth provider stores itself.
  */
 export class CredentialVault {
     storage;
@@ -96,7 +107,7 @@ export class CredentialVault {
         this.storage = storage;
         const raw = base64ToBytes(encryptionKey.trim());
         if (raw.byteLength !== KEY_BYTES) {
-            throw new Error("credentials.encryptionKey must be a base64-encoded 32-byte key");
+            throw new Error("The credential vault encryption key must be a base64-encoded 32-byte key");
         }
         this.key = crypto.subtle.importKey("raw", raw, { name: "AES-GCM" }, false, ["encrypt", "decrypt"]);
     }
@@ -182,6 +193,37 @@ export class CredentialVault {
     async delete(connectorId, owner) {
         await this.storage.delete(storageKey(connectorId, owner));
     }
+    /** Encrypt downstream OAuth state under the vault key; nothing is stored. */
+    async seal(connectorId, purpose, plaintext, owner) {
+        const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+        const ciphertext = await crypto.subtle.encrypt({
+            name: "AES-GCM",
+            iv,
+            additionalData: oauthStateAdditionalData(connectorId, purpose, owner),
+        }, await this.key, encoder.encode(plaintext));
+        return `${SEALED_VERSION}.${bytesToBase64(iv)}.${bytesToBase64(new Uint8Array(ciphertext))}`;
+    }
+    /** Decrypt what `seal` produced for this connector, purpose, and owner. */
+    async open(connectorId, purpose, sealed, owner) {
+        const [version, iv, ciphertext, ...rest] = sealed.split(".");
+        if (version !== SEALED_VERSION ||
+            iv === undefined ||
+            ciphertext === undefined ||
+            rest.length > 0) {
+            throw new Error("Sealed OAuth state is invalid or corrupted");
+        }
+        try {
+            const plaintext = await crypto.subtle.decrypt({
+                name: "AES-GCM",
+                iv: base64ToBytes(iv),
+                additionalData: oauthStateAdditionalData(connectorId, purpose, owner),
+            }, await this.key, base64ToBytes(ciphertext));
+            return decoder.decode(plaintext);
+        }
+        catch {
+            throw new Error("Sealed OAuth state could not be decrypted");
+        }
+    }
 }
 export function encryptedCredentialVault(storage, encryptionKey) {
     return new CredentialVault(storage, encryptionKey);

package/dist/errors.d.ts

@@ -2,11 +2,19 @@
  * Machine-readable classification of a failed connector tool call.
  *
  * A code earns its place by changing what the caller does next, never by
- * naming a cause — the rule provider conventions call H11.
+ * naming a cause — the rule provider conventions call H11, defined in
+ * `test/provider-conventions.test.ts`.
  */
 export type ConnectorCallErrorCode = "timeout" | "auth_required" | "rate_limited" | "unavailable" | "invalid_args"
-/** Provider-owned absence; see provider-conventions.md H11 for the rule and
- * the permission-ambiguity exception. */
+/**
+ * Provider-owned absence: the caller re-addresses rather than waiting,
+ * re-authorizing, or repairing arguments, and a program looping over ids can
+ * continue past it where `connector_call_failed` would abort. Map a status
+ * here only where the provider distinguishes absence from a permission gap —
+ * where it does not (Notion's `object_not_found` covers both), the honest
+ * code stays `connector_call_failed` or `auth_required` with a message that
+ * states the ambiguity (H11).
+ */
  | "not_found" | "input_required_unsupported" | "connector_call_failed";
 /** One bounded, payload-free explanation of an input-schema mismatch. */
 export interface ArgumentValidationIssue {

package/dist/errors.js

@@ -20,7 +20,8 @@ function boundedIssueText(value, maxChars) {
  * the payload lands in both the text content and `structuredContent`. The agent
  * already holds what it sent; the echo is a convenience, never the record.
  */
-// Shared by argument and text echoes; see meta-tools.md lines 360-372.
+// One budget shared by the argument and text echoes, so a caller cannot make a
+// refusal larger by splitting what it sent across the two.
 const MAX_ECHOED_BYTES = 512;
 /**
  * The same budget spent on caller-authored *text* — the address it mistyped,