deepline 0.3.7 → 0.3.8

package/dist/bundling-sources/sdk/src/play.ts

@@ -152,6 +152,8 @@ import type {
   PlaySecretAuthInput,
   PlaySecretAwareRequestInit,
   PlaySecretHandle,
+  PlaySecretPromise,
+  PlaySecretValue,
   PlaySqlQuery,
   PlayReceiptWaitMs,
   PlayRuntimeTimeoutMs,
@@ -253,6 +255,8 @@ export type SqlListenerEvent<T extends object = Record<string, unknown>> =
 /** @deprecated Pass a SQL string directly to ctx.customerDb.query. */
 export type SqlQuery = PlaySqlQuery;
 export type SecretHandle = PlaySecretHandle;
+export type SecretPromise = PlaySecretPromise;
+export type SecretValue = PlaySecretValue;
 export type SecretAuth = PlaySecretAuth;
 export type SecretAuthInput = PlaySecretAuthInput;
 export type SecretAwareRequestInit = PlaySecretAwareRequestInit;

package/dist/bundling-sources/sdk/src/release.ts

@@ -192,7 +192,7 @@ export const SDK_RELEASE = {
   // 0.3.0 introduces raw-v2: complete scrubbed provider responses are
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
-  version: '0.3.7',
+  version: '0.3.8',
   updateSummary:
     'New raw-v2 tool responses preserve complete scrubbed provider envelopes at toolResponse.rawV2, including JSON:API included resources, links, cursors, and totals. Existing toolResponse.raw and declared getters keep working unchanged.',
   contracts: {

package/dist/bundling-sources/shared_libs/play-runtime/context.ts

@@ -168,6 +168,9 @@ import {
   validateOptionalPlayAuthoringField,
   validatePlayAuthoringField,
   type PlayAuthoringContractEdition,
+  type PlaySecretAuth,
+  type PlaySecretAwareRequestInit,
+  type PlaySecretPromise,
   type PlaySqlQuery,
   type PlayAuthoringRunScope,
   type PlayAuthoringRuntimeContext,
@@ -260,17 +263,24 @@ import type { DocflowObservationUpsert } from './docflow-observation';
 import {
   assertNoSecretTaint,
   assertSecretAuthUsesTls,
+  createBase64SecretValue,
   createBearerSecretAuth,
   createHeaderSecretAuth,
+  createPlaintextSecretPromise,
+  createSecretConcat,
   createSecretHandle,
   isSecretAuthInput,
+  isPlaintextSecretPromise,
+  isSecretHandle,
   secretAuthEntries,
   secretAuthHeaderMarkers,
   valueContainsSecret,
   type SecretAuth,
+  type SecretAuthValue,
   type SecretAuthInput,
   type SecretAwareRequestInit,
   type SecretHandle,
+  type SecretValue,
 } from './secret-capability';
 import type {
   CsvOptions,
@@ -1218,7 +1228,9 @@ function publicToolResponseForBatchedItem(
  * from callToolAPI. Keep that input contract stable; raw-v2 is attached to the
  * completed logical call separately by publicToolResponseForBatchedItem.
  */
-function legacyResultForBatchSplitter(execution: ParsedToolExecuteResponse): unknown {
+function legacyResultForBatchSplitter(
+  execution: ParsedToolExecuteResponse,
+): unknown {
   if (execution.toolResponse && 'raw' in execution.toolResponse) {
     return execution.toolResponse.raw;
   }
@@ -2260,18 +2272,33 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   };
 
   readonly secrets = {
-    get: (name: string): SecretHandle => {
+    get: (name: string): PlaySecretPromise => {
       if (typeof name !== 'string' || !name.trim()) {
         throw new Error('ctx.secrets.get(name) requires a non-empty name.');
       }
-      return createSecretHandle(name.trim());
+      const handle = createSecretHandle(name.trim());
+      const value =
+        this.currentAuthoringContractEdition >= 4
+          ? createPlaintextSecretPromise(handle.name, () =>
+              this.resolveSecretHandle(handle),
+            )
+          : handle;
+      return value as unknown as PlaySecretPromise;
     },
-    bearer: (secret: SecretHandle): SecretAuth => {
-      return createBearerSecretAuth(secret);
+    bearer: (secret: SecretAuthValue): PlaySecretAuth => {
+      return createBearerSecretAuth(secret) as unknown as PlaySecretAuth;
     },
-    header: (header: string, secret: SecretHandle): SecretAuth => {
-      return createHeaderSecretAuth(header, secret);
+    header: (header: string, secret: SecretAuthValue): PlaySecretAuth => {
+      return createHeaderSecretAuth(
+        header,
+        secret,
+      ) as unknown as PlaySecretAuth;
     },
+    // Only editions 1–3 call these runtime-only compatibility helpers. Edition
+    // 4's public authoring contract intentionally exposes normal strings.
+    concat: (...parts: readonly (string | SecretValue)[]): SecretValue =>
+      createSecretConcat(parts),
+    base64: (value: SecretValue): SecretValue => createBase64SecretValue(value),
   };
 
   constructor(options: ContextOptions) {
@@ -2780,10 +2807,52 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
   private async resolveSingleSecretAuth(auth: SecretAuth) {
     if (!auth) return {};
+    const value = await this.resolveSecretAuthValue(auth.secret);
+    if (auth.kind === 'bearer') {
+      return { authorization: `Bearer ${value}` };
+    }
+    return { [auth.header.toLowerCase()]: value };
+  }
+
+  private async resolveSecretAuthValue(
+    secret: SecretAuthValue,
+  ): Promise<string> {
+    if (typeof secret === 'string') {
+      this.secretRedactor.register(secret);
+      return secret;
+    }
+    if (isPlaintextSecretPromise(secret)) {
+      const value = await secret;
+      this.secretRedactor.register(value);
+      return value;
+    }
+    return this.resolveSecretValue(secret as SecretValue);
+  }
+
+  private async resolveSecretValue(secret: SecretValue): Promise<string> {
+    if (isSecretHandle(secret)) return this.resolveSecretHandle(secret);
+    const value =
+      secret.kind === 'concat'
+        ? (
+            await Promise.all(
+              secret.parts.map((part) =>
+                typeof part === 'string' ? part : this.resolveSecretValue(part),
+              ),
+            )
+          ).join('')
+        : Buffer.from(
+            await this.resolveSecretValue(secret.value),
+            'utf8',
+          ).toString('base64');
+    this.secretRedactor.register(value);
+    return value;
+  }
+
+  private async resolveSecretHandle(secret: SecretHandle): Promise<string> {
     let value: string | null = null;
     if (this.#options.resolveSecret) {
       value = await this.#options.resolveSecret({
-        name: auth.secret.name,
+        name: secret.name,
         playName: this.#options.playName,
         orgId: this.#options.orgId,
         workflowId: this.#options.workflowId,
@@ -2824,7 +2893,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             },
             body: JSON.stringify({
               action: 'resolve_secret',
-              name: auth.secret.name,
+              name: secret.name,
               playName: this.#options.playName,
             }),
           });
@@ -2837,7 +2906,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           this.log(
             `[runtime.secret_resolution_failure] ${JSON.stringify({
               stage: 'transport',
-              secret_name: auth.secret.name,
+              secret_name: secret.name,
               gateway_origin: transportGatewayOriginForDiagnostic(url),
               operation_id: operationId,
               request_id: requestId,
@@ -2852,7 +2921,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           );
           if (!retry.retry) {
             throw new Error(
-              `Secret ${auth.secret.name} resolution transport failed (request_id=${requestId}): ${diagnostic.message ?? 'unknown transport error'}`,
+              `Secret ${secret.name} resolution transport failed (request_id=${requestId}): ${diagnostic.message ?? 'unknown transport error'}`,
             );
           }
           await waitForSecretResolutionRetry(retry.retryDelayMs);
@@ -2865,7 +2934,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           : NO_SECRET_RESOLUTION_RETRY;
         const responseDiagnostic = {
           stage: response.ok ? 'invalid_response' : 'http_response',
-          secret_name: auth.secret.name,
+          secret_name: secret.name,
           gateway_origin: transportGatewayOriginForDiagnostic(url),
           operation_id: operationId,
           request_id: requestId,
@@ -2898,7 +2967,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             continue;
           }
           throw new Error(
-            `Secret ${auth.secret.name} is not available to this run (resolution status=${response.status}, request_id=${requestId}).`,
+            `Secret ${secret.name} is not available to this run (resolution status=${response.status}, request_id=${requestId}).`,
           );
         }
 
@@ -2915,7 +2984,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             })}`,
           );
           throw new Error(
-            `Secret ${auth.secret.name} is not available to this run (invalid resolution response, request_id=${requestId}).`,
+            `Secret ${secret.name} is not available to this run (invalid resolution response, request_id=${requestId}).`,
           );
         }
 
@@ -2939,13 +3008,13 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             })}`,
           );
           throw new Error(
-            `Secret ${auth.secret.name} is not available to this run (missing resolution value, request_id=${requestId}).`,
+            `Secret ${secret.name} is not available to this run (missing resolution value, request_id=${requestId}).`,
           );
         }
         if (attempt > 1) {
           this.log(
             `[runtime.secret_resolution_recovered] ${JSON.stringify({
-              secret_name: auth.secret.name,
+              secret_name: secret.name,
               gateway_origin: transportGatewayOriginForDiagnostic(url),
               operation_id: operationId,
               request_id: requestId,
@@ -2962,15 +3031,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       );
     }
     if (!value) {
-      throw new Error(
-        `Secret ${auth.secret.name} is not available to this run.`,
-      );
+      throw new Error(`Secret ${secret.name} is not available to this run.`);
     }
     this.secretRedactor.register(value);
-    if (auth.kind === 'bearer') {
-      return { authorization: `Bearer ${value}` };
-    }
-    return { [auth.header.toLowerCase()]: value };
+    return value;
   }
 
   private setMapFrame(frame: MapExecutionFrame): void {
@@ -9709,7 +9773,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
   log(msg: string): void {
     assertNoSecretTaint(msg, 'ctx.log');
-    const line = `[${new Date().toISOString()}] ${msg}`;
+    const line = `[${new Date().toISOString()}] ${this.secretRedactor.redactRegisteredSecrets(msg)}`;
     this.logBuffer.push(line);
     this.#options.onLog?.(line);
     if (this.#options.verbose) console.log(line);
@@ -9750,7 +9814,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   async fetch(
     key: string,
     input: string | URL,
-    init: SecretAwareRequestInit = {},
+    init: PlaySecretAwareRequestInit | SecretAwareRequestInit = {},
     options?: FetchOptions,
   ): Promise<PlayFetchResponse> {
     validatePlayAuthoringField('ctx.fetch.key', key);
@@ -9765,25 +9829,68 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         }
       : null;
 
-    if (valueContainsSecret(input) || valueContainsSecret(init.body)) {
+    const url = input.toString();
+    const parsedUrl = new URL(url);
+    const urlContainsResolvedSecret =
+      this.secretRedactor.containsRegisteredSecret(url, {
+        includeEncoded: true,
+        minimumLength: 4,
+      }) ||
+      [...parsedUrl.searchParams.values()].some((value) =>
+        this.secretRedactor.matchesRegisteredSecret(value),
+      );
+    if (valueContainsSecret(input) || urlContainsResolvedSecret) {
+      throw new Error(
+        'ctx.fetch does not allow secrets in the URL. Use an approved secret auth helper or request body.',
+      );
+    }
+    if (valueContainsSecret(init.body)) {
       throw new Error(
-        'ctx.fetch does not allow secrets in the URL or body. Use an approved secret auth helper.',
+        'ctx.fetch does not allow opaque secret values in the body. Await ctx.secrets.get(...) before constructing the body.',
       );
     }
-    if (valueContainsSecret(init.headers)) {
+    const requestBody = typeof init.body === 'string' ? init.body : null;
+    const bodyContainsResolvedSecret =
+      requestBody !== null &&
+      this.secretRedactor.containsRegisteredSecret(requestBody, {
+        includeEncoded: true,
+      });
+    if (bodyContainsResolvedSecret && parsedUrl.protocol !== 'https:') {
+      throw new Error(
+        'ctx.fetch with a resolved secret in the request body requires an https:// URL. Customer secrets may only leave Deepline over TLS.',
+      );
+    }
+    const receiptBody = bodyContainsResolvedSecret
+      ? this.secretRedactor.redactRegisteredSecrets(requestBody)
+      : requestBody;
+    const rawHeaders = normalizeFetchHeaders(init.headers);
+    if (
+      valueContainsSecret(init.headers) ||
+      Object.values(rawHeaders).some(
+        (value) =>
+          this.secretRedactor.matchesRegisteredSecret(value) ||
+          this.secretRedactor.containsRegisteredSecret(value, {
+            minimumLength: 4,
+          }),
+      )
+    ) {
       throw new Error(
         'ctx.fetch does not allow raw secret headers. Use ctx.secrets.bearer(...) or ctx.secrets.header(...).',
       );
     }
-    if (init.auth !== undefined && !isSecretAuthInput(init.auth)) {
-      throw new Error('ctx.fetch auth must come from ctx.secrets.');
+    let secretAuth: SecretAuthInput | undefined;
+    if (init.auth !== undefined) {
+      if (!isSecretAuthInput(init.auth)) {
+        throw new Error('ctx.fetch auth must come from ctx.secrets.');
+      }
+      secretAuth = init.auth;
     }
     // Secret handles are deliberately resolved at the last possible moment, so
     // plaintext never lands in durable keys, receipts, map rows, or generic tool
     // payloads. The one place a customer secret is allowed to leave Deepline is
     // the requested auth header, and that transport must be TLS.
-    assertSecretAuthUsesTls(init.auth, input, 'ctx.fetch');
-    const secretHeaderMarkers = secretAuthHeaderMarkers(init.auth);
+    assertSecretAuthUsesTls(secretAuth, input, 'ctx.fetch');
+    const secretHeaderMarkers = secretAuthHeaderMarkers(secretAuth);
 
     const execution = this.executeWithRuntimeReceipt<PlayFetchResponse>(
       'fetch',
@@ -9793,8 +9900,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         semanticKey: stableDigest(
           stableStringify({
             method: (init.method ?? 'GET').toUpperCase(),
-            url: input.toString(),
-            body: typeof init.body === 'string' ? init.body : null,
+            url,
+            body: receiptBody,
             safeHeaders: {
               ...normalizeFetchHeaders(init.headers),
               ...secretHeaderMarkers,
@@ -9804,9 +9911,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         ),
         staleAfterSeconds: options?.staleAfterSeconds,
         execute: async ({ retainExternalCallSlot }) => {
-          const url = input.toString();
           const method = (init.method ?? 'GET').toUpperCase();
-          const secretHeaders = await this.resolveSecretAuth(init.auth);
+          const secretHeaders = await this.resolveSecretAuth(secretAuth);
           const headers: Record<string, string> = {
             ...normalizeFetchHeaders(init.headers),
             ...secretHeaders,
@@ -9822,7 +9928,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   ...normalizeFetchHeaders(init.headers),
                   ...secretHeaderMarkers,
                 },
-                body: typeof init.body === 'string' ? init.body : null,
+                body: receiptBody,
                 row: rowFetchScope,
               }),
             )}`,
@@ -9909,6 +10015,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                     safePublicFetch(url, attemptInit, {
                       fetchImpl: this.#options.fetchImpl,
                       sensitiveHeaders: Object.keys(secretHeaderMarkers),
+                      stripHeadersOnCrossOriginRedirect: true,
                     }),
                 });
                 bodyText = await readCtxFetchBody({

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona-lifecycle.ts

@@ -15,7 +15,7 @@ import { DAYTONA_PLAY_RUNNER_LABEL_SOURCE } from './daytona-labels';
 const DAYTONA_CREATE_TIMEOUT_SECONDS = 10;
 const DAYTONA_CREATE_RETRY_DELAYS_MS = [0, 500, 1_500] as const;
 const DAYTONA_TIMED_OUT_CREATE_RECONCILE_DELAYS_MS = [
-  0, 250, 750, 1_500, 3_000,
+  0, 1_000, 3_000, 6_000, 12_000,
 ] as const;
 // Explicit runner deadline + scheduler GC own the normal lifecycle. Daytona's
 // inactivity stop is a wider crash backstop measured from sandbox creation, so

package/dist/bundling-sources/shared_libs/play-runtime/secret-capability.ts

@@ -2,10 +2,16 @@ import type {
   PlaySecretAuth,
   PlaySecretAwareRequestInit,
   PlaySecretHandle,
+  PlaySecretPromise,
 } from '../plays/authoring-contract';
+import { sha256Hex } from '../plays/row-identity';
 
 const SECRET_HANDLE_BRAND = Symbol.for('deepline.secret.handle');
 const SECRET_AUTH_BRAND = Symbol.for('deepline.secret.auth');
+const SECRET_VALUE_BRAND = Symbol.for('deepline.secret.value');
+const SECRET_PLAINTEXT_PROMISE_BRAND = Symbol.for(
+  'deepline.secret.plaintext-promise',
+);
 const SECRET_HANDLE_MARKER_RE = /\[secret:[A-Z0-9_ -]+\]/i;
 
 export type SecretHandle = PlaySecretHandle & {
@@ -15,26 +21,61 @@ export type SecretHandle = PlaySecretHandle & {
   toJSON(): never;
 };
 
-export type SecretAuth = PlaySecretAuth &
+/**
+ * Runtime-only opaque values retained to execute authoring-contract editions
+ * 1–3. Edition 4's public Play type deliberately no longer exposes these
+ * helpers; published legacy artifacts still invoke them at runtime.
+ */
+type SecretExpression =
+  | {
+      readonly [SECRET_VALUE_BRAND]: true;
+      readonly kind: 'concat';
+      readonly parts: readonly (string | SecretValue)[];
+      toString(): string;
+      toJSON(): never;
+    }
+  | {
+      readonly [SECRET_VALUE_BRAND]: true;
+      readonly kind: 'base64';
+      readonly value: SecretValue;
+      toString(): string;
+      toJSON(): never;
+    };
+
+export type SecretValue = SecretHandle | SecretExpression;
+export type PlaintextSecretPromise = PlaySecretPromise & {
+  readonly [SECRET_PLAINTEXT_PROMISE_BRAND]: true;
+  readonly name: string;
+};
+export type SecretAuthValue =
+  | string
+  | PlaySecretPromise
+  | PlaintextSecretPromise
+  | PlaySecretHandle
+  | SecretValue;
+
+export type SecretAuth = Omit<PlaySecretAuth, 'secret'> &
   (
     | {
         readonly [SECRET_AUTH_BRAND]: true;
         readonly kind: 'bearer';
-        readonly secret: SecretHandle;
+        readonly secret: SecretAuthValue;
       }
     | {
         readonly [SECRET_AUTH_BRAND]: true;
         readonly kind: 'header';
         readonly header: string;
-        readonly secret: SecretHandle;
+        readonly secret: SecretAuthValue;
       }
   );
 
 export type SecretAuthInput = SecretAuth | readonly SecretAuth[];
 
-export type SecretAwareRequestInit = PlaySecretAwareRequestInit & {
-  auth?: SecretAuthInput;
-};
+export type SecretAwareRequestInit =
+  | PlaySecretAwareRequestInit
+  | (Omit<PlaySecretAwareRequestInit, 'auth'> & {
+      auth?: SecretAuthInput;
+    });
 
 function isRecord(value: unknown): value is Record<string | symbol, unknown> {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
@@ -44,6 +85,25 @@ export function isSecretHandle(value: unknown): value is SecretHandle {
   return isRecord(value) && value[SECRET_HANDLE_BRAND] === true;
 }
 
+export function isSecretValue(value: unknown): value is SecretValue {
+  return (
+    isSecretHandle(value) ||
+    (isRecord(value) && value[SECRET_VALUE_BRAND] === true)
+  );
+}
+
+export function isPlaintextSecretPromise(
+  value: unknown,
+): value is PlaintextSecretPromise {
+  return (
+    Boolean(value) &&
+    typeof value === 'object' &&
+    (value as Record<string | symbol, unknown>)[
+      SECRET_PLAINTEXT_PROMISE_BRAND
+    ] === true
+  );
+}
+
 export function isSecretAuth(value: unknown): value is SecretAuth {
   return isRecord(value) && value[SECRET_AUTH_BRAND] === true;
 }
@@ -69,7 +129,7 @@ export function valueContainsSecret(value: unknown): boolean {
   const seen = new WeakSet<object>();
   while (pending.length > 0) {
     const candidate = pending.pop();
-    if (isSecretHandle(candidate) || isSecretAuth(candidate)) return true;
+    if (isSecretValue(candidate) || isSecretAuth(candidate)) return true;
     if (typeof candidate === 'string') {
       if (SECRET_HANDLE_MARKER_RE.test(candidate)) return true;
       continue;
@@ -99,19 +159,47 @@ export function createSecretHandle(name: string): SecretHandle {
   } as unknown as SecretHandle;
 }
 
-export function createBearerSecretAuth(secret: SecretHandle): SecretAuth {
-  if (!isSecretHandle(secret)) {
-    throw new Error('ctx.secrets.bearer(...) requires a SecretHandle.');
+export function createPlaintextSecretPromise(
+  name: string,
+  resolve: () => Promise<string>,
+): PlaintextSecretPromise {
+  const value = resolve() as PlaintextSecretPromise;
+  Object.defineProperties(value, {
+    [SECRET_PLAINTEXT_PROMISE_BRAND]: { value: true },
+    name: { value: name },
+  });
+  return value;
+}
+
+export function createBearerSecretAuth(secret: SecretAuthValue): SecretAuth {
+  // A generic promise has no secret provenance or stable receipt marker. Only
+  // the promise created by ctx.secrets.get(...) carries the runtime brand.
+  if (
+    typeof secret !== 'string' &&
+    !isSecretValue(secret) &&
+    !isPlaintextSecretPromise(secret)
+  ) {
+    throw new Error(
+      'ctx.secrets.bearer(...) requires a resolved string or legacy secret handle. Await ctx.secrets.get(...) first.',
+    );
   }
   return { [SECRET_AUTH_BRAND]: true, kind: 'bearer', secret };
 }
 
 export function createHeaderSecretAuth(
   header: string,
-  secret: SecretHandle,
+  secret: SecretAuthValue,
 ): SecretAuth {
-  if (!isSecretHandle(secret)) {
-    throw new Error('ctx.secrets.header(...) requires a SecretHandle.');
+  // Keep this check in sync with bearer: ordinary promises must be awaited
+  // before auth construction, while the branded get() promise is compatible.
+  if (
+    typeof secret !== 'string' &&
+    !isSecretValue(secret) &&
+    !isPlaintextSecretPromise(secret)
+  ) {
+    throw new Error(
+      'ctx.secrets.header(...) requires a resolved string or legacy secret handle. Await ctx.secrets.get(...) first.',
+    );
   }
   if (typeof header !== 'string' || !header.trim()) {
     throw new Error('ctx.secrets.header(...) requires a header name.');
@@ -124,6 +212,62 @@ export function createHeaderSecretAuth(
   };
 }
 
+export function createSecretConcat(
+  parts: readonly (string | SecretValue)[],
+): SecretValue {
+  if (parts.length === 0 || !parts.some(isSecretValue)) {
+    throw new Error(
+      'ctx.secrets.concat(...) requires at least one secret value.',
+    );
+  }
+  if (!parts.every((part) => typeof part === 'string' || isSecretValue(part))) {
+    throw new Error(
+      'ctx.secrets.concat(...) accepts strings and secret values only.',
+    );
+  }
+  return {
+    [SECRET_VALUE_BRAND]: true,
+    kind: 'concat',
+    parts,
+    toString: () => '[secret-expression]',
+    toJSON: () => {
+      throw new Error(
+        'Secret expressions cannot be serialized. Use them only with ctx.secrets auth helpers.',
+      );
+    },
+  } as SecretValue;
+}
+
+export function createBase64SecretValue(value: SecretValue): SecretValue {
+  if (!isSecretValue(value)) {
+    throw new Error('ctx.secrets.base64(...) requires a secret value.');
+  }
+  return {
+    [SECRET_VALUE_BRAND]: true,
+    kind: 'base64',
+    value,
+    toString: () => '[secret-expression]',
+    toJSON: () => {
+      throw new Error(
+        'Secret expressions cannot be serialized. Use them only with ctx.secrets auth helpers.',
+      );
+    },
+  } as SecretValue;
+}
+
+export function secretValueMarker(value: SecretValue): string {
+  if (isSecretHandle(value)) return `[secret:${value.name}]`;
+  if (value.kind === 'base64')
+    return `[secret-base64:${secretValueMarker(value.value)}]`;
+  return `[secret-concat:${value.parts
+    .map((part) =>
+      typeof part === 'string'
+        ? `[literal:${sha256Hex(part)}]`
+        : secretValueMarker(part),
+    )
+    .join('+')}]`;
+}
+
 export function secretAuthHeaderMarkers(
   auth: SecretAuthInput | undefined,
 ): Record<string, string> {
@@ -136,7 +280,12 @@ export function secretAuthHeaderMarkers(
         `ctx.fetch cannot attach more than one secret to the ${header} header.`,
       );
     }
-    markers[header] = `[secret:${entry.secret.name}]`;
+    markers[header] =
+      typeof entry.secret === 'string'
+        ? `[secret-plaintext:${sha256Hex(entry.secret)}]`
+        : isPlaintextSecretPromise(entry.secret)
+          ? `[secret:${entry.secret.name}]`
+          : secretValueMarker(entry.secret as SecretValue);
   }
   return markers;
 }