@zackbart/connecta 0.24.4 → 0.26.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

@@ -15,7 +15,14 @@ export type ConnectorCallErrorCode = "timeout" | "auth_required" | "rate_limited
  * code stays `connector_call_failed` or `auth_required` with a message that
  * states the ambiguity (H11).
  */
- | "not_found" | "input_required_unsupported" | "connector_call_failed";
+ | "not_found"
+/**
+ * The write named a base version or revision that is no longer current:
+ * someone else changed the thing first. The caller re-reads, reapplies its
+ * change, and retries with the base `current` reports — repeating the same
+ * call can never succeed, and waiting will not help either.
+ */
+ | "conflict" | "input_required_unsupported" | "connector_call_failed";
 /** One bounded, payload-free explanation of an input-schema mismatch. */
 export interface ArgumentValidationIssue {
     /** JSON Pointer into the submitted arguments; "/" means the root value. */
@@ -88,12 +95,18 @@ export declare class ConnectorCallError extends Error {
     readonly validation: ArgumentValidationDetails | undefined;
     /** Sanitized transport diagnostics for `unavailable` only. */
     readonly details: UnavailableDetails | undefined;
+    /**
+     * For `conflict` only: where each thing the write touched stands now, e.g.
+     * `{ revision: 12, view: 7 }`. Bounded to 20 whole-number entries.
+     */
+    readonly current: Readonly<Record<string, number>> | undefined;
     constructor(code: ConnectorCallErrorCode, message: string, opts?: {
         retryable?: boolean;
         retryAfterMs?: number;
         cause?: unknown;
         validation?: ArgumentValidationDetails;
         details?: UnavailableDetails;
+        current?: Readonly<Record<string, number>>;
     });
 }
 /** The `error` object surfaced in value-mode call results and rejected promises. */
@@ -107,6 +120,8 @@ export interface CallErrorDetails {
     retryAfterMs?: number;
     /** Bounded input-schema findings; paths and expectations, never values. */
     validation?: ArgumentValidationDetails;
+    /** On a `conflict`: where each thing the write touched stands now. */
+    current?: Readonly<Record<string, number>>;
     /** Connector whose failed operation needs recovery. */
     connector?: string;
     /** Canonical downstream address the agent may retry after recovery. */

package/dist/errors.js

@@ -162,9 +162,30 @@ const RETRYABLE_BY_CODE = {
     auth_required: false,
     invalid_args: false,
     not_found: false,
+    conflict: false,
     input_required_unsupported: false,
     connector_call_failed: false,
 };
+/** Entries a conflict's `current` map may carry. */
+const MAX_CURRENT_ENTRIES = 20;
+const MAX_CURRENT_KEY_CHARS = 128;
+/**
+ * Where each thing a conflicting write touched stands now: short names to
+ * whole non-negative numbers, at most 20 of them. Anything else is dropped
+ * whole rather than clipped, because a truncated key names a different thing.
+ */
+function boundedCurrent(current) {
+    if (!current || typeof current !== "object")
+        return undefined;
+    const entries = Object.entries(current).filter(([key, value]) => key.length > 0 &&
+        key.length <= MAX_CURRENT_KEY_CHARS &&
+        key !== "__proto__" &&
+        Number.isSafeInteger(value) &&
+        value >= 0);
+    if (entries.length === 0)
+        return undefined;
+    return Object.freeze(Object.fromEntries(entries.slice(0, MAX_CURRENT_ENTRIES)));
+}
 /** Non-negative integer milliseconds, or undefined for anything else. */
 function normalizeRetryAfterMs(value) {
     if (value === undefined)
@@ -201,6 +222,11 @@ export class ConnectorCallError extends Error {
     validation;
     /** Sanitized transport diagnostics for `unavailable` only. */
     details;
+    /**
+     * For `conflict` only: where each thing the write touched stands now, e.g.
+     * `{ revision: 12, view: 7 }`. Bounded to 20 whole-number entries.
+     */
+    current;
     constructor(code, message, opts = {}) {
         super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
         this.name = "ConnectorCallError";
@@ -211,6 +237,7 @@ export class ConnectorCallError extends Error {
             code === "unavailable" ? sanitizedUnavailableDetails(opts.details) : undefined;
         this.validation =
             code === "invalid_args" ? boundedValidation(opts.validation) : undefined;
+        this.current = code === "conflict" ? boundedCurrent(opts.current) : undefined;
     }
 }
 /**
@@ -262,6 +289,7 @@ export function classifyCallError(err, fallbackCode = "connector_call_failed") {
                 : {}),
             ...(err.validation ? { validation: err.validation } : {}),
             ...(err.details ? { details: err.details } : {}),
+            ...(err.current ? { current: err.current } : {}),
         };
     }
     // An aborted fetch rejects with a DOMException named "AbortError" whose