@cef-ai/widget-runtime 0.2.0 → 1.0.0

package/dist/audio/capture-upload.d.ts

@@ -63,37 +63,52 @@ export interface VaultStoreConfig {
      */
     credentialLabel?: string;
 }
-export interface VaultUploaderConfig extends VaultStoreConfig {
-    /** Path prefix inside the bucket. Defaults to `widget-audio/<uuid>`. */
-    keyPrefix?: string;
-    /**
-     * Read URL mode for downstream model fetches.
-     *
-     * Default `signed` keeps Vault audio private; the URL is bound to this
-     * client's own credential (revoking that credential invalidates it).
-     * `public` writes `x-amz-acl: public-read` and returns the plain object URL;
-     * use only for controlled dev/test flows or a deliberate public asset policy.
-     */
-    readMode?: 'signed' | 'public';
-}
 export type VaultUploadFn = ((wav: ArrayBuffer, index: number) => Promise<string>) & {
     finalizeUrls: (urls: string[]) => Promise<string[]>;
 };
 /**
- * Creates a WAV uploader that writes to a DDC S3-compatible vault bucket using
- * the proven in-browser flow from the spike:
- *   1. Derive signer from embed wallet (ed25519_signRaw).
- *   2. GET /auth/info → gateway_public_key.
- *   3. Mint delegation token (subject = gateway_public_key).
- *   4. POST /auth/credentials with signed headers — always mints a NEW,
- *      labeled credential for this uploader (cap-400 → reclaim our oldest
- *      labeled row and retry once).
- *   5. Per segment: SHA-256 WAV bytes, PUT via SigV4-signed AwsClient.
- *
- * S3 credentials are memoized (shared credential core) so the signer is only
- * invoked once per uploader instance under normal operation.
+ * Structural subset of `vault.scope(name).objects` (`@cef-ai/vault-sdk`,
+ * ADR-002) the object uploader needs. Kept local — same rationale as
+ * `vault-client.ts`'s `VaultSdkLike` — so this stays unit-testable against a
+ * plain fake and decoupled from vault-sdk internals.
+ */
+export interface VaultObjectsLike {
+    upload(path: string, data: Uint8Array, opts?: {
+        contentType?: string;
+    }): Promise<{
+        vaultPath: string;
+    }>;
+    presignedUrl(path: string, opts?: {
+        ttlSeconds?: number;
+    }): Promise<{
+        url: string;
+        expiresAt: string;
+    }>;
+}
+export interface VaultObjectUploaderConfig {
+    /** `vault.scope(manifest.scope).objects` — see ADR-002. */
+    objects: VaultObjectsLike;
+    /** Path prefix inside the scope's object namespace. Defaults to `widget-audio/<uuid>`. */
+    keyPrefix?: string;
+    /** TTL for the signed read URL handed back to the caller (model-side fetch). Server default if omitted. */
+    readTtlSeconds?: number;
+}
+/**
+ * Creates a WAV uploader on top of Vault API's object storage (ADR-002),
+ * replacing the direct-to-DDC-S3-Gateway SigV4 uploader this function used
+ * to be: no delegation token, no gateway credential, no client-side
+ * signing — every call is an ordinary authenticated Vault API request, the
+ * same auth the rest of the widget runtime already uses for cubby reads and
+ * publish. There is no credential to go stale mid-batch — but a chunk's
+ * presigned URL, minted right after ITS upload finishes, still has its own
+ * TTL clock ticking independent of auth: on a long capture, chunk 0's URL
+ * can age past `readTtlSeconds` (server default if unset) before the whole
+ * batch is even done uploading, let alone before whatever reads it (ASR)
+ * gets to it. So unlike the old uploader's no-op `finalizeUrls`, this one
+ * re-mints every chunk's URL right before handoff — every URL's TTL clock
+ * starts at the same moment, the end of the batch, not staggered across it.
  */
-export declare function createVaultUploader(cfg: VaultUploaderConfig): VaultUploadFn;
+export declare function createVaultObjectUploader(cfg: VaultObjectUploaderConfig): VaultUploadFn;
 /** Read/write whole objects at caller-chosen keys in a DDC vault bucket. */
 export interface VaultObjectStore {
     /**
@@ -105,12 +120,19 @@ export interface VaultObjectStore {
     signGet(key: string, ttlSeconds?: number): Promise<string>;
 }
 /**
- * Whole-file companion to createVaultUploader: PUT an object at a STABLE,
- * caller-chosen key and re-sign GET URLs for it on demand. Used to persist a
- * durable interview recording (store the key, not the expiring presigned URL)
- * and re-sign playback URLs from the candidate modal — same private bucket,
- * same wallet, so the grant can always be re-minted. Shares the auth flow with
- * the segment uploader via createCredCore.
+ * PUT an object at a STABLE, caller-chosen key and re-sign GET URLs for it on
+ * demand — direct to the DDC S3 Gateway via SigV4, the same pattern
+ * `createVaultObjectUploader` above replaces for WAV chunk uploads (ADR-002:
+ * company-memory-bank 04-cef/user-vault/decisions/ADR-002-vault-object-storage.md).
+ *
+ * **Not yet migrated.** This function has no known consumer inside this
+ * repo — it's exported public API with no first-party caller to migrate
+ * alongside `createVaultUploader`. Left in place rather than migrated
+ * speculatively or deleted blind (removing exported API without knowing its
+ * consumers is its own risk). If you're adding a caller, prefer Vault API
+ * object storage (`vault.scope(name).objects.upload/presignedUrl`) over this —
+ * this function is the same abstraction leak the ADR closes, just not yet
+ * closed here.
  */
 export declare function createVaultObjectStore(cfg: VaultStoreConfig): VaultObjectStore;
 export {};

package/dist/audio/capture-upload.js

@@ -120,8 +120,10 @@ async function registerCredentials(ctx, delegationToken, label) {
 }
 /**
  * Acquire vault-bucket S3 credentials once and expose a memoized AwsClient.
- * Shared by createVaultObjectStore AND createVaultUploader; the in-browser
- * auth flow —
+ * Used by createVaultObjectStore (the direct-to-DDC-S3-Gateway whole-object
+ * store — see its own doc comment for why this SigV4 path still exists
+ * post-ADR-002, unlike the WAV chunk uploader above which now goes through
+ * Vault API object storage instead). The in-browser auth flow —
  *   1. GET /auth/info → gateway_public_key.
  *   2. Mint delegation token (subject = gateway_public_key).
  *   3. POST /auth/credentials with signed headers — always mints a NEW,
@@ -132,7 +134,12 @@ async function registerCredentials(ctx, delegationToken, label) {
  * revoke-each-other race anymore.
  */
 function createCredCore(cfg) {
-    const fetchImpl = cfg.fetchImpl ?? globalThis.fetch;
+    // Bind to globalThis: browsers (Blink/WebKit) brand-check fetch's receiver
+    // against window and throw "Illegal invocation" when it's called detached
+    // (`const f = globalThis.fetch; f(...)`). Node's fetch doesn't brand-check and
+    // tests inject cfg.fetchImpl, so an unbound default stayed green in CI but
+    // broke every real browser upload on the first /auth call.
+    const fetchImpl = cfg.fetchImpl ?? globalThis.fetch.bind(globalThis);
     const awsClientFactory = cfg.awsClientFactory ?? ((creds) => new AwsClient({ accessKeyId: creds.accessKeyId, secretAccessKey: creds.secretAccessKey, region: creds.region, service: 's3', ...(creds.sessionToken ? { sessionToken: creds.sessionToken } : {}) }));
     const label = cfg.credentialLabel ?? CREDENTIAL_LABEL;
     const ctx = {
@@ -224,109 +231,48 @@ async function putWithRetry(core, url, body, contentType, onAttempt) {
         throw new Error(`PUT ${url} → ${res.status} ${await res.text()}`);
 }
 /**
- * Creates a WAV uploader that writes to a DDC S3-compatible vault bucket using
- * the proven in-browser flow from the spike:
- *   1. Derive signer from embed wallet (ed25519_signRaw).
- *   2. GET /auth/info → gateway_public_key.
- *   3. Mint delegation token (subject = gateway_public_key).
- *   4. POST /auth/credentials with signed headers — always mints a NEW,
- *      labeled credential for this uploader (cap-400 → reclaim our oldest
- *      labeled row and retry once).
- *   5. Per segment: SHA-256 WAV bytes, PUT via SigV4-signed AwsClient.
- *
- * S3 credentials are memoized (shared credential core) so the signer is only
- * invoked once per uploader instance under normal operation.
+ * Creates a WAV uploader on top of Vault API's object storage (ADR-002),
+ * replacing the direct-to-DDC-S3-Gateway SigV4 uploader this function used
+ * to be: no delegation token, no gateway credential, no client-side
+ * signing — every call is an ordinary authenticated Vault API request, the
+ * same auth the rest of the widget runtime already uses for cubby reads and
+ * publish. There is no credential to go stale mid-batch — but a chunk's
+ * presigned URL, minted right after ITS upload finishes, still has its own
+ * TTL clock ticking independent of auth: on a long capture, chunk 0's URL
+ * can age past `readTtlSeconds` (server default if unset) before the whole
+ * batch is even done uploading, let alone before whatever reads it (ASR)
+ * gets to it. So unlike the old uploader's no-op `finalizeUrls`, this one
+ * re-mints every chunk's URL right before handoff — every URL's TTL clock
+ * starts at the same moment, the end of the batch, not staggered across it.
  */
-export function createVaultUploader(cfg) {
-    const core = createCredCore(cfg);
-    // Compute keyPrefix once per instance (not per call).
+export function createVaultObjectUploader(cfg) {
     const keyPrefix = cfg.keyPrefix ?? `widget-audio/${crypto.randomUUID()}`;
-    const uploadedObjects = new Map();
-    // Presign (signed mode) or return the plain public URL. We deliberately do NOT
-    // read-back-verify each chunk: a credential refresh mid-batch (the PUT-retry
-    // path below) invalidates URLs presigned with the replaced credential — an
-    // intermittent SignatureDoesNotMatch on a verify GET that has no business
-    // failing the upload. `finalizeUrls` re-signs every object with the final
-    // stable credential after all chunks land, and the ASR stage retries its own
-    // reads; that is the stable path the pre-refactor uploader used (see
-    // docs/engineering/known-issues/2026-06-01-widget-audio-private-bucket-asr-403.md).
-    async function readableUrlForObject(aws, objectUrl) {
-        if (cfg.readMode === 'public')
-            return objectUrl;
-        const signed = await aws.sign(`${objectUrl}?X-Amz-Expires=${core.readTtl}`, { aws: { signQuery: true } });
-        return signed.url;
-    }
+    const presignOpts = cfg.readTtlSeconds ? { ttlSeconds: cfg.readTtlSeconds } : {};
     const uploadWav = (async function uploadWav(wav, index) {
-        const wavBytes = new Uint8Array(wav);
-        const contentSha256 = await sha256Hex(wavBytes);
-        // SigV4 region from the bucket (cfg.region), not creds.region.
-        const region = cfg.region;
-        const url = `${cfg.gatewayUrl}/${cfg.bucketId}/${keyPrefix}/${index}.wav`;
-        // Bounded 401/403 retry with backoff. Under the multi-credential gateway a
-        // 403 no longer means a concurrent session revoked our credential, so the
-        // first retry RE-USES the already-minted credential (transient gateway /
-        // propagation hiccups). If the failure persists past attempt 2, refresh the
-        // credential (the underlying DDC delegation token may have expired); the
-        // replaced row is revoked by id, so retries never leak rows toward the cap.
-        const maxAttempts = 4;
-        let lastStatus = 0;
-        let lastText = '';
-        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-            const aws = await core.aws();
-            // NOTE: never log the RETURNED presigned url — it carries a bearer SigV4 sig.
-            console.log('[wr-up] PUT region=', region, 'bucket=', cfg.bucketId, 'index=', index, 'attempt=', attempt, 'bytes=', wavBytes.length, 'sha=', contentSha256.slice(0, 16));
-            const putRes = await aws.fetch(url, {
-                method: 'PUT',
-                // Send a Blob (an immutable, exact byte sequence) rather than the Uint8Array
-                // view: the browser transmits EXACTLY the bytes we hashed, so the gateway's
-                // recomputed SHA256(body) matches the signed X-Amz-Content-Sha256. Passing a
-                // typed-array view to fetch() can transmit its whole backing ArrayBuffer in
-                // the browser (not in Node) — that skew was the SignatureDoesNotMatch on
-                // segmented chunks. The gateway rejects UNSIGNED-PAYLOAD, so we sign the real
-                // content hash.
-                body: new Blob([wavBytes], { type: 'audio/wav' }),
-                headers: {
-                    'Content-Type': 'audio/wav',
-                    'X-Amz-Content-Sha256': contentSha256,
-                    ...(cfg.readMode === 'public' ? { 'x-amz-acl': 'public-read' } : {}),
-                },
-            });
-            if (putRes.ok) {
-                uploadedObjects.set(index, url);
-                return await readableUrlForObject(aws, url);
-            }
-            lastStatus = putRes.status;
-            lastText = await putRes.text();
-            if ((putRes.status === 403 || putRes.status === 401) && attempt < maxAttempts) {
-                if (attempt >= 2)
-                    await core.refresh();
-                await new Promise((r) => setTimeout(r, 600 * attempt));
-                continue;
-            }
-            break;
-        }
-        throw new Error(`PUT ${url} → ${lastStatus} ${lastText}`);
+        const path = `${keyPrefix}/${index}.wav`;
+        await cfg.objects.upload(path, new Uint8Array(wav), { contentType: 'audio/wav' });
+        const signed = await cfg.objects.presignedUrl(path, presignOpts);
+        return signed.url;
     });
     uploadWav.finalizeUrls = async (urls) => {
-        if (uploadedObjects.size === 0)
-            return urls;
-        const aws = await core.aws();
-        const entries = [...uploadedObjects.entries()].sort(([a], [b]) => a - b);
-        const signed = [];
-        for (const [, objectUrl] of entries) {
-            signed.push(await readableUrlForObject(aws, objectUrl));
-        }
-        return signed;
+        return Promise.all(urls.map(async (_url, index) => (await cfg.objects.presignedUrl(`${keyPrefix}/${index}.wav`, presignOpts)).url));
     };
     return uploadWav;
 }
 /**
- * Whole-file companion to createVaultUploader: PUT an object at a STABLE,
- * caller-chosen key and re-sign GET URLs for it on demand. Used to persist a
- * durable interview recording (store the key, not the expiring presigned URL)
- * and re-sign playback URLs from the candidate modal — same private bucket,
- * same wallet, so the grant can always be re-minted. Shares the auth flow with
- * the segment uploader via createCredCore.
+ * PUT an object at a STABLE, caller-chosen key and re-sign GET URLs for it on
+ * demand — direct to the DDC S3 Gateway via SigV4, the same pattern
+ * `createVaultObjectUploader` above replaces for WAV chunk uploads (ADR-002:
+ * company-memory-bank 04-cef/user-vault/decisions/ADR-002-vault-object-storage.md).
+ *
+ * **Not yet migrated.** This function has no known consumer inside this
+ * repo — it's exported public API with no first-party caller to migrate
+ * alongside `createVaultUploader`. Left in place rather than migrated
+ * speculatively or deleted blind (removing exported API without knowing its
+ * consumers is its own risk). If you're adding a caller, prefer Vault API
+ * object storage (`vault.scope(name).objects.upload/presignedUrl`) over this —
+ * this function is the same abstraction leak the ADR closes, just not yet
+ * closed here.
  */
 export function createVaultObjectStore(cfg) {
     const core = createCredCore(cfg);

package/dist/bridge-wallet.d.ts

@@ -37,8 +37,9 @@ export declare function toVaultSdkSigner(pubkey: string, sigType: 'ed25519' | 's
  */
 export declare function toClientSdkWallet(pubkey: string, sigType: 'ed25519' | 'sr25519', signFn: (bytes: Uint8Array) => Promise<Uint8Array>): VaultSignedWallet;
 /**
- * Build the signerPair shape that `createVaultUploader` (and `mintDelegationToken`)
- * accept, from a bridge pubkey + sign function.
+ * Build the signerPair shape that the SigV4-signing DDC S3 Gateway clients
+ * (`createVaultObjectStore`, `mintDelegationToken`) accept, from a bridge
+ * pubkey + sign function.
  */
 export declare function toUploaderSignerPair(pubkey: string, signFn: (bytes: Uint8Array) => Promise<Uint8Array>): {
     publicKey: Uint8Array;

package/dist/bridge-wallet.js

@@ -5,7 +5,11 @@
 //
 //   toVaultSdkSigner    → @cef-ai/signer `Signer` (type/address/publicKey/isReady/sign)
 //   toClientSdkWallet   → @cef-ai/client-sdk VaultSignedWallet
-//   toUploaderSignerPair → { publicKey: Uint8Array; sign } for createVaultUploader
+//   toUploaderSignerPair → { publicKey: Uint8Array; sign } for the SigV4-signing
+//                          DDC S3 Gateway clients (createVaultObjectStore,
+//                          mintDelegationToken) — NOT for WAV chunk uploads,
+//                          which go through createVaultObjectUploader (Vault
+//                          API object storage, ADR-002) and need no signer.
 //
 // All hex values in the client-sdk shape are WITHOUT a 0x prefix, matching
 // the proven embed-wallet behaviour (see embed-adapter.ts history).
@@ -69,8 +73,9 @@ export function toClientSdkWallet(pubkey, sigType, signFn) {
     };
 }
 /**
- * Build the signerPair shape that `createVaultUploader` (and `mintDelegationToken`)
- * accept, from a bridge pubkey + sign function.
+ * Build the signerPair shape that the SigV4-signing DDC S3 Gateway clients
+ * (`createVaultObjectStore`, `mintDelegationToken`) accept, from a bridge
+ * pubkey + sign function.
  */
 export function toUploaderSignerPair(pubkey, signFn) {
     return {

package/dist/entry.js

@@ -1,11 +1,11 @@
 // packages/widget-runtime/src/entry.ts
 import { VaultSDK } from '@cef-ai/vault-sdk';
 import { createHostBridge } from './host-bridge.js';
-import { toVaultSdkSigner, toUploaderSignerPair } from './bridge-wallet.js';
+import { toVaultSdkSigner } from './bridge-wallet.js';
 import { connectStandaloneWallet } from './standalone-wallet.js';
 import { createVaultClient } from './vault-client.js';
 import { createWidgetRuntime } from './runtime.js';
-import { captureAndUploadAudio, createVaultUploader } from './audio/capture-upload.js';
+import { captureAndUploadAudio, createVaultObjectUploader } from './audio/capture-upload.js';
 import { decodeToMono16k } from './audio/segment.js';
 import { registerCompositePanel } from './kinds/composite.js';
 /**
@@ -91,16 +91,24 @@ function boot() {
     // The uploader resolves its identity lazily via the shared (memoized)
     // resolver on the first upload — it never blocks WidgetRuntime exposure and
     // reuses the same host-or-wallet signer as the vault client.
+    //
+    // ADR-002 (company-memory-bank 04-cef/user-vault/decisions/): chunks upload
+    // through Vault API object storage, not the DDC S3 Gateway directly — no
+    // delegation token, no gateway credential, no client-side SigV4 signing.
+    // The `vault.scope(...).objects` handle is real vault-sdk (not the
+    // structural VaultClient abstraction createVaultClient wraps), so it's
+    // built directly here from the same signer + endpoints as the main vault
+    // client above.
     let mountDeps;
     if (manifest.kind === 'submit' || manifest.kind === 'conversation' || manifest.kind === 'composite') {
-        // Memoize: build uploader once, reuse across multiple uploads in same session.
+        // Memoize: build the uploader once, reuse across multiple uploads in the
+        // same session (mirrors the pre-ADR-002 uploader's memoization).
         let uploaderP = null;
         const getUploader = () => {
             if (uploaderP)
                 return uploaderP;
             uploaderP = (async () => {
                 const id = await resolveSigningIdentity();
-                const signerPair = toUploaderSignerPair(id.publicKey, id.sign);
                 const vaultSdkSigner = toVaultSdkSigner(id.publicKey, id.sigType, id.sign);
                 const sdk = new VaultSDK({
                     endpoint: manifest.endpoints.vault,
@@ -110,13 +118,7 @@ function boot() {
                     signer: vaultSdkSigner,
                 });
                 const ensuredVault = await sdk.vault.ensure({ onboard: false });
-                return createVaultUploader({
-                    signerPair,
-                    sigType: id.sigType,
-                    gatewayUrl: manifest.endpoints.s3GatewayAuthInfo.replace(/\/auth\/info\/?$/, ''),
-                    bucketId: ensuredVault.bucketId,
-                    region: ensuredVault.region,
-                });
+                return createVaultObjectUploader({ objects: ensuredVault.scope(manifest.scope).objects });
             })().catch((err) => { uploaderP = null; throw err; });
             return uploaderP;
         };

package/dist/index.d.ts

@@ -13,8 +13,8 @@ export { renderConversation } from './kinds/conversation.js';
 export { renderComposite, registerCompositePanel, getCompositePanel, type CompositePanelRenderer } from './kinds/composite.js';
 export * from './render-helpers.js';
 export type { WidgetKind, WidgetConfig, RecordConfig, ListConfig, DashboardConfig, SubmitConfig, ConversationConfig, CustomPanelConfig, CompositePanel, CompositeConfig } from './types.js';
-export { captureAndUploadAudio, createVaultUploader, createVaultObjectStore } from './audio/capture-upload.js';
-export type { CaptureUploadInput, CaptureUploadDeps, VaultUploaderConfig, VaultStoreConfig, VaultObjectStore } from './audio/capture-upload.js';
+export { captureAndUploadAudio, createVaultObjectUploader, createVaultObjectStore } from './audio/capture-upload.js';
+export type { CaptureUploadInput, CaptureUploadDeps, VaultObjectUploaderConfig, VaultObjectsLike, VaultStoreConfig, VaultObjectStore } from './audio/capture-upload.js';
 export { mintDelegationToken, Operation } from './audio/ddc-delegation.js';
 export type { AsyncSignerPair, MintOpts } from './audio/ddc-delegation.js';
 export { encodeWav } from './audio/wav.js';

package/dist/index.js

@@ -11,7 +11,7 @@ export { renderSubmit } from './kinds/submit.js';
 export { renderConversation } from './kinds/conversation.js';
 export { renderComposite, registerCompositePanel, getCompositePanel } from './kinds/composite.js';
 export * from './render-helpers.js';
-export { captureAndUploadAudio, createVaultUploader, createVaultObjectStore } from './audio/capture-upload.js';
+export { captureAndUploadAudio, createVaultObjectUploader, createVaultObjectStore } from './audio/capture-upload.js';
 export { mintDelegationToken, Operation } from './audio/ddc-delegation.js';
 export { encodeWav } from './audio/wav.js';
 export { segmentPcm, decodeToMono16k } from './audio/segment.js';