fix(storage): close snapshot policy review gaps

Generated-by: OpenAI Codex

Author: MicroGery

packages/storage/src/__tests__/quiescent-session-snapshot.test.ts

@@ -1,5 +1,25 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
 import assert from 'node:assert/strict';
 import {
+  copyFile,
   mkdir,
   mkdtemp,
   readFile,
@@ -31,8 +51,8 @@ afterEach(async () => {
 
 test('prepares state and workspace under one quiescence boundary, then releases live writers', async () => {
   const fixture = await createFixture();
-  let liveState = 'state-at-boundary';
-  let liveWorkspace = 'workspace-at-boundary';
+  await writeFile(join(fixture.liveStateRoot, 'runtime.sqlite'), 'state-at-boundary', 'utf8');
+  await writeFile(join(fixture.liveWorkspaceRoot, 'main.ts'), 'workspace-at-boundary', 'utf8');
   const events: string[] = [];
   let quiescent = false;
 
@@ -57,7 +77,10 @@ test('prepares state and workspace under one quiescence boundary, then releases
         assert.equal(quiescent, true);
         events.push('state');
         await mkdir(input.destinationRoot);
-        await writeFile(join(input.destinationRoot, 'runtime.sqlite'), liveState, 'utf8');
+        await copyFile(
+          join(fixture.liveStateRoot, 'runtime.sqlite'),
+          join(input.destinationRoot, 'runtime.sqlite'),
+        );
         return {
           mediaType: 'application/vnd.maka.session-state-identity+json;version=1',
           bytes: Buffer.from('{"makaSessionId":"session-1"}', 'utf8'),
@@ -70,7 +93,10 @@ test('prepares state and workspace under one quiescence boundary, then releases
         assert.equal(input.policy, SESSION_SNAPSHOT_WORKSPACE_POLICY_V1);
         events.push('workspace');
         await mkdir(input.destinationRoot);
-        await writeFile(join(input.destinationRoot, 'main.ts'), liveWorkspace, 'utf8');
+        await copyFile(
+          join(fixture.liveWorkspaceRoot, 'main.ts'),
+          join(input.destinationRoot, 'main.ts'),
+        );
         return workspaceResult({ includedEntries: 1 });
       },
     },
@@ -82,15 +108,15 @@ test('prepares state and workspace under one quiescence boundary, then releases
   assert.notEqual(handle.snapshot.workspaceRoot, fixture.liveWorkspaceRoot);
   assert.equal(
     await readFile(join(handle.snapshot.stateRoot, 'runtime.sqlite'), 'utf8'),
-    liveState,
+    'state-at-boundary',
   );
   assert.equal(
     await readFile(join(handle.snapshot.workspaceRoot, 'main.ts'), 'utf8'),
-    liveWorkspace,
+    'workspace-at-boundary',
   );
 
-  liveState = 'later-state';
-  liveWorkspace = 'later-workspace';
+  await writeFile(join(fixture.liveStateRoot, 'runtime.sqlite'), 'later-state', 'utf8');
+  await writeFile(join(fixture.liveWorkspaceRoot, 'main.ts'), 'later-workspace', 'utf8');
   assert.equal(
     await readFile(join(handle.snapshot.stateRoot, 'runtime.sqlite'), 'utf8'),
     'state-at-boundary',
@@ -308,6 +334,41 @@ test('cancellation and an expired deadline stop before staging begins', async ()
   assert.deepEqual(await readdir(fixture.stagingParent), []);
 });
 
+test('a deadline beyond the Node timer limit is rescheduled until the absolute time', async (t) => {
+  t.mock.timers.enable({ apis: ['Date', 'setTimeout'], now: 0 });
+  const fixture = await createFixture();
+  const authorityEntered = deferred<void>();
+  let cancellationSignal: AbortSignal | undefined;
+  const coordinator = createFileQuiescentSessionSnapshotCoordinator({
+    stagingParent: fixture.stagingParent,
+    privateStagingRootAuthority,
+    now: Date.now,
+    quiescence: {
+      async runQuiescent(input) {
+        cancellationSignal = input.cancellation.signal;
+        authorityEntered.resolve();
+        await waitForAbort(input.cancellation);
+        throw Object.assign(new Error('aborted'), { name: 'AbortError' });
+      },
+    },
+    state: directoryStatePreparer,
+    workspace: directoryWorkspacePreparer,
+  });
+  const timerLimit = 2_147_483_647;
+  const preparation = coordinator.prepare({
+    makaSessionId: 'long-deadline',
+    deadlineAt: timerLimit + 1_000,
+  });
+  await authorityEntered.promise;
+
+  t.mock.timers.tick(timerLimit);
+  assert.equal(cancellationSignal?.aborted, false);
+  t.mock.timers.tick(999);
+  assert.equal(cancellationSignal?.aborted, false);
+  t.mock.timers.tick(1);
+  await assert.rejects(preparation, isSnapshotError('snapshot_cancelled'));
+});
+
 test('cancellation while waiting for quiescence is propagated as snapshot_cancelled', async () => {
   const fixture = await createFixture();
   const authorityEntered = deferred<void>();
@@ -547,12 +608,21 @@ test('V1 workspace policy includes portable inputs, excludes rebuildable data, a
     ['.turbo/cache.bin', 'file', { kind: 'exclude', category: 'cache' }],
     ['logs/agent.txt', 'file', { kind: 'exclude', category: 'log' }],
     ['debug.log', 'file', { kind: 'exclude', category: 'log' }],
-    ['secrets.log', 'file', { kind: 'exclude', category: 'log' }],
+    ['secrets.log', 'file', { kind: 'reject', category: 'known_secret_file' }],
+    ['.env.log', 'file', { kind: 'reject', category: 'known_secret_file' }],
+    ['keys/private-key.log', 'file', { kind: 'reject', category: 'known_secret_file' }],
     ['.maka-runtime/input.json', 'file', { kind: 'exclude', category: 'runtime_scratch' }],
     ['.env.local', 'file', { kind: 'reject', category: 'known_secret_file' }],
+    ['.env.example', 'file', { kind: 'include' }],
+    ['.env.template', 'file', { kind: 'include' }],
+    ['.env.example.local', 'file', { kind: 'reject', category: 'known_secret_file' }],
     ['keys/id_ed25519', 'file', { kind: 'reject', category: 'known_secret_file' }],
+    ['keys/id_ed25519.pub', 'file', { kind: 'include' }],
+    ['keys/id_rsa.pub', 'file', { kind: 'include' }],
     ['credentials.yaml', 'file', { kind: 'reject', category: 'known_secret_file' }],
     ['secrets.json', 'file', { kind: 'reject', category: 'known_secret_file' }],
+    ['src/secrets.ts', 'file', { kind: 'include' }],
+    ['docs/secrets.md', 'file', { kind: 'include' }],
     ['.terraformrc', 'file', { kind: 'reject', category: 'known_secret_file' }],
     ['.git-credentials.lock', 'file', { kind: 'reject', category: 'known_secret_file' }],
     ['keys/client-private-key.pem', 'file', { kind: 'reject', category: 'known_secret_file' }],
@@ -562,7 +632,13 @@ test('V1 workspace policy includes portable inputs, excludes rebuildable data, a
     ['certs/client.csr', 'file', { kind: 'include' }],
     ['certs/client.pem', 'file', { kind: 'include' }],
     ['certs/client.der', 'file', { kind: 'include' }],
+    ['privkey.pem', 'file', { kind: 'reject', category: 'known_secret_file' }],
+    ['private.pem', 'file', { kind: 'reject', category: 'known_secret_file' }],
     ['keys/service-account.json', 'file', { kind: 'reject', category: 'known_secret_file' }],
+    ['secrets', 'directory', { kind: 'reject', category: 'known_secret_file' }],
+    ['secrets/token', 'file', { kind: 'reject', category: 'known_secret_file' }],
+    ['credentials/oauth.json', 'file', { kind: 'reject', category: 'known_secret_file' }],
+    ['private/token', 'file', { kind: 'reject', category: 'known_secret_file' }],
     ['.ssh/config', 'file', { kind: 'reject', category: 'known_secret_file' }],
     ['.aws/credentials', 'file', { kind: 'reject', category: 'known_secret_file' }],
     ['.cargo/credentials', 'file', { kind: 'reject', category: 'known_secret_file' }],
@@ -575,6 +651,11 @@ test('V1 workspace policy includes portable inputs, excludes rebuildable data, a
     ],
     ['../escape', 'file', { kind: 'reject', category: 'unsafe_path' }],
     ['a\\b', 'file', { kind: 'reject', category: 'unsafe_path' }],
+    ['CON', 'file', { kind: 'reject', category: 'unsafe_path' }],
+    ['nested/LPT1.txt', 'file', { kind: 'reject', category: 'unsafe_path' }],
+    ['foo:bar', 'file', { kind: 'reject', category: 'unsafe_path' }],
+    ['name.', 'file', { kind: 'reject', category: 'unsafe_path' }],
+    ['name ', 'directory', { kind: 'reject', category: 'unsafe_path' }],
   ] as const;
 
   for (const [relativePath, kind, expected] of cases) {

packages/storage/src/quiescent-session-snapshot.ts

@@ -1,3 +1,22 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
 import { randomUUID } from 'node:crypto';
 import { constants as fsConstants } from 'node:fs';
 import { lstat, mkdir, open, realpath, rename, rm } from 'node:fs/promises';
@@ -7,6 +26,7 @@ import type {
   OpaqueStateIdentityDescriptor,
   PreparedSessionBundleSnapshot,
 } from './session-bundle-contract.js';
+import { isSessionBundleUstarPathV1 } from './session-bundle-ustar.js';
 import { isSafeSessionId } from './session-store.js';
 
 export const SESSION_SNAPSHOT_POLICY_VERSION = 1 as const;
@@ -15,6 +35,7 @@ export const SESSION_SNAPSHOT_STAGING_SCHEMA_VERSION = 1 as const;
 const SNAPSHOT_ID_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
 const MAX_OWNER_RECORD_BYTES = 1_024;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
 const NO_FOLLOW_OPEN_FLAG = process.platform === 'win32' ? 0 : fsConstants.O_NOFOLLOW;
 
 export type SessionSnapshotWorkspaceEntryKind = 'file' | 'directory';
@@ -63,12 +84,20 @@ const INCLUDE = Object.freeze({ kind: 'include' } as const);
 // measurement rules introduced by #1353. Snapshot rejection is reserved for
 // names that identify known secret material; public certificate encodings and
 // other ambiguous formats are not rejected by extension alone.
+const PUBLIC_ENV_TEMPLATE_PATTERN = /^\.env\.(?:example|sample|template)$/i;
+const KNOWN_SECRET_WORKSPACE_DIRECTORY_NAMES = new Set([
+  '.ssh',
+  'credentials',
+  'private',
+  'secrets',
+]);
 const KNOWN_SECRET_WORKSPACE_FILE_PATTERNS = [
   /^\.env(?:\..*)?$/i,
   /^\.(?:npmrc|netrc|pypirc|terraformrc)$/i,
   /^\.git-credentials(?:\.lock)?$/i,
-  /^(?:credentials?|secrets?)(?:\..*)?$/i,
+  /^(?:credentials?|secrets?)(?:\.(?:cfg|conf|ini|json|log|properties|toml|ya?ml))?$/i,
   /(?:^|[-_.])(?:id_(?:rsa|dsa|ecdsa|ed25519)|private[-_.]?key)(?:$|[-_.])/i,
+  /^(?:private|privkey)\.pem$/i,
   /\.(?:key|p12|pfx)$/i,
 ] as const;
 
@@ -101,19 +130,19 @@ export const SESSION_SNAPSHOT_WORKSPACE_POLICY_V1: SessionSnapshotWorkspacePolic
     ) {
       return { kind: 'exclude', category: 'cache' };
     }
+    if (lowerSegments.includes('.maka-runtime') || lowerSegments.includes('.maka-activation')) {
+      return { kind: 'exclude', category: 'runtime_scratch' };
+    }
+    if (isKnownSecretEntry(entry.kind, lowerSegments, lowerName)) {
+      return { kind: 'reject', category: 'known_secret_file' };
+    }
     if (
       lowerSegments.includes('logs') ||
       lowerSegments.includes('.logs') ||
       (entry.kind === 'file' && lowerName.endsWith('.log'))
     ) {
       return { kind: 'exclude', category: 'log' };
     }
-    if (lowerSegments.includes('.maka-runtime') || lowerSegments.includes('.maka-activation')) {
-      return { kind: 'exclude', category: 'runtime_scratch' };
-    }
-    if (entry.kind === 'file' && isKnownSecretPath(lowerSegments, lowerName)) {
-      return { kind: 'reject', category: 'known_secret_file' };
-    }
     return INCLUDE;
   },
 });
@@ -371,7 +400,7 @@ class FileQuiescentSessionSnapshotCoordinator implements QuiescentSessionSnapsho
             prepared = handle;
             return handle;
           } catch (error) {
-            await cleanupAfterPreparationFailure(staging, error);
+            return cleanupAfterPreparationFailure(staging, error);
           }
         },
       );
@@ -649,22 +678,29 @@ function decodeWorkspaceEntry(
   if (segments.some((segment) => segment.length === 0 || segment === '.' || segment === '..')) {
     return { kind: 'reject', category: 'unsafe_path' };
   }
+  const bundlePath = `workspace/${entry.relativePath}${entry.kind === 'directory' ? '/' : ''}`;
+  if (!isSessionBundleUstarPathV1(bundlePath)) {
+    return { kind: 'reject', category: 'unsafe_path' };
+  }
   return { kind: 'valid', segments, basename: segments.at(-1)! };
 }
 
-function isKnownSecretPath(lowerSegments: readonly string[], lowerName: string): boolean {
+function isKnownSecretEntry(
+  kind: SessionSnapshotWorkspaceEntryKind,
+  lowerSegments: readonly string[],
+  lowerName: string,
+): boolean {
+  if (lowerSegments.some((segment) => KNOWN_SECRET_WORKSPACE_DIRECTORY_NAMES.has(segment))) {
+    return true;
+  }
+  if (kind === 'directory') return false;
+  if (PUBLIC_ENV_TEMPLATE_PATTERN.test(lowerName) || lowerName.endsWith('.pub')) return false;
   if (KNOWN_SECRET_WORKSPACE_FILE_PATTERNS.some((pattern) => pattern.test(lowerName))) return true;
-  if (
-    lowerSegments.includes('.ssh') ||
-    lowerName === 'service-account.json' ||
-    lowerName === 'service-account-key.json'
-  ) {
+  if (lowerName === 'service-account.json' || lowerName === 'service-account-key.json') {
     return true;
   }
   return (
     (lowerSegments.at(-2) === '.docker' && lowerName === 'config.json') ||
-    (lowerSegments.at(-2) === '.aws' && lowerName === 'credentials') ||
-    (lowerSegments.at(-2) === '.cargo' && lowerName === 'credentials') ||
     (lowerSegments.at(-2) === '.kube' && lowerName === 'config') ||
     (lowerSegments.at(-2) === 'gcloud' &&
       lowerSegments.at(-3) === '.config' &&
@@ -785,12 +821,19 @@ function createCancellation(
   const controller = new AbortController();
   const abort = () => controller.abort();
   input.signal?.addEventListener('abort', abort, { once: true });
+  let timeout: NodeJS.Timeout | undefined;
+  const scheduleDeadline = () => {
+    if (input.deadlineAt === undefined) return;
+    const remaining = input.deadlineAt - now();
+    if (remaining <= 0) {
+      abort();
+      return;
+    }
+    timeout = setTimeout(scheduleDeadline, Math.min(remaining, MAX_TIMER_DELAY_MS));
+    timeout.unref();
+  };
   const remaining = input.deadlineAt === undefined ? undefined : input.deadlineAt - now();
-  const timeout =
-    remaining === undefined || remaining <= 0
-      ? undefined
-      : setTimeout(abort, Math.min(remaining, 2_147_483_647));
-  timeout?.unref();
+  if (remaining !== undefined && remaining > 0) scheduleDeadline();
   if (input.signal?.aborted || (remaining !== undefined && remaining <= 0)) abort();
   const value = Object.freeze({
     signal: controller.signal,

packages/storage/src/session-bundle-ustar.ts

@@ -38,6 +38,17 @@ export interface SessionBundleUstarHeader {
   size: number;
 }
 
+/** Return whether a path belongs to the exact portable path language used by Bundle V1. */
+export function isSessionBundleUstarPathV1(path: string): boolean {
+  try {
+    splitUstarPath(path);
+    return true;
+  } catch (error) {
+    if (error instanceof SessionBundleFileError && error.code === 'unsafe_path') return false;
+    throw error;
+  }
+}
+
 /**
  * Encode the exact POSIX USTAR header admitted by Session Bundle codec V1.
  * Paths use a portable subset on every host: Windows device names, forbidden