@detiq/api-tests 0.0.0-stage → 1.1.26

package/.env.example

@@ -0,0 +1,24 @@
+# API Testing Environment Configuration
+# Copy to .env.test and fill in values for your environment.
+
+# Base URL of the API under test
+API_TEST_BASE_URL=https://staging.api.example.com
+
+# Environment identifier — used by EnvironmentGuard to block MUTATING tests on prod
+# Values: dev | staging | qa | prod | production
+API_TEST_ENV=staging
+
+# Static bearer token for bearer_static auth profile tests
+API_TEST_BEARER_TOKEN=
+
+# API key for api_key auth profile tests
+API_TEST_API_KEY=
+
+# Password for basic or jwt_login auth profile tests
+API_TEST_PASSWORD=
+
+# Set to 'true' to enable LOAD_SENSITIVE tests (rate limit, concurrency)
+API_TEST_ENABLE_LOAD=false
+
+# Set to 'true' to allow MUTATING tests to run on production (requires explicit approval)
+API_TEST_ALLOW_MUTATING_ON_PROD=false

package/ci/github-actions.yml

@@ -0,0 +1,127 @@
+name: API Tests
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main, staging]
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: 'Target environment'
+        required: true
+        default: 'staging'
+        type: choice
+        options: [dev, staging, qa]
+      enable_load_tests:
+        description: 'Enable LOAD_SENSITIVE tests'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  api-tests:
+    name: API Tests (${{ github.event.inputs.environment || 'staging' }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright
+        run: npx playwright install --with-deps chromium
+        # API tests don't use a browser but Playwright install is required
+
+      - name: Run API tests (SAFE)
+        env:
+          API_TEST_BASE_URL: ${{ secrets[format('API_TEST_BASE_URL_{0}', upper(github.event.inputs.environment || 'STAGING'))] }}
+          API_TEST_ENV: ${{ github.event.inputs.environment || 'staging' }}
+          API_TEST_BEARER_TOKEN: ${{ secrets[format('API_TEST_BEARER_TOKEN_{0}', upper(github.event.inputs.environment || 'STAGING'))] }}
+          API_TEST_API_KEY: ${{ secrets[format('API_TEST_API_KEY_{0}', upper(github.event.inputs.environment || 'STAGING'))] }}
+          API_TEST_ENABLE_LOAD: ${{ github.event.inputs.enable_load_tests || 'false' }}
+        run: |
+          cd packages/api-tests
+          npx playwright test --grep @safe --reporter=junit,list
+
+      - name: Run API tests (MUTATING - staging only)
+        if: github.event.inputs.environment == 'staging' || github.ref == 'refs/heads/staging'
+        env:
+          API_TEST_BASE_URL: ${{ secrets.API_TEST_BASE_URL_STAGING }}
+          API_TEST_ENV: staging
+          API_TEST_BEARER_TOKEN: ${{ secrets.API_TEST_BEARER_TOKEN_STAGING }}
+        run: |
+          cd packages/api-tests
+          npx playwright test --grep @mutating --reporter=junit,list
+
+      - name: Run Security tests
+        env:
+          API_TEST_BASE_URL: ${{ secrets[format('API_TEST_BASE_URL_{0}', upper(github.event.inputs.environment || 'STAGING'))] }}
+          API_TEST_ENV: ${{ github.event.inputs.environment || 'staging' }}
+          API_TEST_BEARER_TOKEN: ${{ secrets[format('API_TEST_BEARER_TOKEN_{0}', upper(github.event.inputs.environment || 'STAGING'))] }}
+        run: |
+          cd packages/api-tests
+          npx playwright test --grep @security --reporter=junit,list
+
+      - name: Upload JUnit results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: api-test-results-junit
+          path: packages/api-tests/test-results/api-results.xml
+
+      - name: Upload JSON results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: api-test-results-json
+          path: packages/api-tests/test-results/api-results.json
+
+      - name: Publish Test Report
+        uses: mikepenz/action-junit-report@v4
+        if: always()
+        with:
+          report_paths: 'packages/api-tests/test-results/api-results.xml'
+          check_name: 'API Test Results'
+          fail_on_failure: true
+          require_tests: false
+
+      - name: Comment PR with test summary
+        uses: actions/github-script@v7
+        if: github.event_name == 'pull_request' && always()
+        with:
+          script: |
+            const fs = require('fs');
+            const jsonPath = 'packages/api-tests/test-results/api-results.json';
+            if (!fs.existsSync(jsonPath)) return;
+            const results = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
+            const stats = results.stats || {};
+            const status = stats.unexpected > 0 ? '❌' : '✅';
+            const body = [
+              `## ${status} API Test Results`,
+              '',
+              `| Metric | Count |`,
+              `|--------|-------|`,
+              `| Total | ${stats.expected + stats.unexpected || 0} |`,
+              `| Passed | ${stats.expected || 0} |`,
+              `| Failed | ${stats.unexpected || 0} |`,
+              `| Skipped | ${stats.skipped || 0} |`,
+              '',
+              stats.unexpected > 0
+                ? '> ⚠️ **CRITICAL API tests failed.** Merge is blocked until failures are resolved.'
+                : '> All API tests passed.',
+            ].join('\n');
+
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body,
+            });

package/ci/gitlab-ci.yml

@@ -0,0 +1,29 @@
+api-tests:
+  stage: test
+  image: mcr.microsoft.com/playwright:v1.47.0-jammy
+  variables:
+    API_TEST_ENV: ${CI_ENVIRONMENT_NAME:-staging}
+  script:
+    - cd packages/api-tests
+    - npm ci
+    - npx playwright test --grep "@safe|@security" --reporter=junit,list
+  artifacts:
+    when: always
+    reports:
+      junit: packages/api-tests/test-results/api-results.xml
+    paths:
+      - packages/api-tests/test-results/
+  only:
+    - merge_requests
+    - main
+    - staging
+
+api-tests-mutating:
+  stage: test
+  extends: api-tests
+  script:
+    - cd packages/api-tests
+    - npm ci
+    - npx playwright test --grep @mutating --reporter=junit,list
+  only:
+    - staging

package/ci/test-result-schema.ts

@@ -0,0 +1,55 @@
+export interface ApiTestRunResult {
+  runId: string;
+  suiteId: string;
+  projectId: string;
+  environment: string;
+  startedAt: string;   // ISO 8601
+  completedAt: string; // ISO 8601
+  durationMs: number;
+  executionRiskBreakdown: {
+    safe: number;
+    mutating: number;
+    loadSensitive: number;
+  };
+  summary: {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+  };
+  criticalFailures: number; // failures where priority === 'CRITICAL'
+  results: ApiTestCaseResult[];
+}
+
+export interface ApiTestCaseResult {
+  testCaseId: string;
+  title: string;
+  dimension: string;
+  kind: string;
+  priority: 'CRITICAL' | 'HIGH' | 'MEDIUM';
+  endpoint: string;
+  executionRisk: 'SAFE' | 'MUTATING' | 'LOAD_SENSITIVE';
+  status: 'passed' | 'failed' | 'skipped' | 'timedOut';
+  durationMs: number;
+  attempts: number;
+  retriedOn?: string[];         // e.g. ['ECONNRESET', '503']
+  actualStatus?: number;        // HTTP status received
+  expectedStatus?: string;      // documented expected status
+  failureReason?: string;
+  requestLog?: ApiRequestLog;
+  responseLog?: ApiResponseLog;
+}
+
+export interface ApiRequestLog {
+  method: string;
+  url: string;
+  headers: Record<string, string>; // sensitive headers masked
+  body?: string;                    // request body (PII masked)
+}
+
+export interface ApiResponseLog {
+  status: number;
+  headers: Record<string, string>;
+  body?: string;  // first 1000 chars
+  durationMs: number;
+}

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "@detiq/api-tests",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.26",
+  "private": false,
+  "type": "module",
+  "scripts": {
+    "test": "playwright test",
+    "test:safe": "playwright test --grep @safe",
+    "test:mutating": "playwright test --grep @mutating",
+    "test:security": "playwright test --grep @security",
+    "test:ci": "playwright test --reporter=junit"
+  },
+  "devDependencies": {
+    "@playwright/test": "workspace:*",
+    "typescript": "workspace:*"
+  },
+  "dependencies": {}
+}

package/playwright.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './src/tests',
+  testMatch: /.*\.api\.spec\.ts$/,
+  timeout: 30_000,
+  retries: 0, // Retry logic is handled per-request in withRetry() — not at test level
+  workers: 4,
+  reporter: [
+    ['list'],
+    ['junit', { outputFile: 'test-results/api-results.xml' }],
+    ['json', { outputFile: 'test-results/api-results.json' }],
+  ],
+  use: {
+    extraHTTPHeaders: {
+      'Accept': 'application/json',
+    },
+  },
+  projects: [
+    {
+      name: 'api',
+      testMatch: /.*\.api\.spec\.ts$/,
+    },
+  ],
+});

package/src/lib/api-client.ts

@@ -0,0 +1,82 @@
+import type { APIRequestContext, APIResponse } from '@playwright/test';
+
+/** Minimal auth profile type for building request headers. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AuthProfile = { type: string; [key: string]: any };
+
+export interface ApiClientOptions {
+  /** Pre-created Playwright API request context. */
+  request: APIRequestContext;
+  /** Optional bearer token — sent as Authorization: Bearer <token>. */
+  bearerToken?: string;
+  /** Additional headers to include on every request. */
+  extraHeaders?: Record<string, string>;
+}
+
+export class BaseApiClient {
+  private readonly request: APIRequestContext;
+  private readonly defaultHeaders: Record<string, string>;
+
+  private constructor(request: APIRequestContext, defaultHeaders: Record<string, string>) {
+    this.request = request;
+    this.defaultHeaders = defaultHeaders;
+  }
+
+  static create(options: ApiClientOptions): BaseApiClient {
+    const headers: Record<string, string> = { ...options.extraHeaders };
+    if (options.bearerToken) {
+      headers['Authorization'] = `Bearer ${options.bearerToken}`;
+    }
+    return new BaseApiClient(options.request, headers);
+  }
+
+  private mergeHeaders(headers?: Record<string, string>): Record<string, string> {
+    return { ...this.defaultHeaders, ...headers };
+  }
+
+  async get(path: string, headers?: Record<string, string>): Promise<APIResponse> {
+    return this.request.get(path, { headers: this.mergeHeaders(headers) });
+  }
+
+  async post(path: string, body: unknown, headers?: Record<string, string>): Promise<APIResponse> {
+    return this.request.post(path, { data: body, headers: this.mergeHeaders(headers) });
+  }
+
+  async put(path: string, body: unknown, headers?: Record<string, string>): Promise<APIResponse> {
+    return this.request.put(path, { data: body, headers: this.mergeHeaders(headers) });
+  }
+
+  async patch(path: string, body: unknown, headers?: Record<string, string>): Promise<APIResponse> {
+    return this.request.patch(path, { data: body, headers: this.mergeHeaders(headers) });
+  }
+
+  async delete(path: string, headers?: Record<string, string>): Promise<APIResponse> {
+    return this.request.delete(path, { headers: this.mergeHeaders(headers) });
+  }
+
+  async dispose(): Promise<void> {
+    await this.request.dispose();
+  }
+}
+
+/** Resolve an AuthProfile to the headers needed for API requests. */
+export function authHeaders(profile: AuthProfile): Record<string, string> {
+  switch (profile.type) {
+    case 'none':
+      return {};
+    case 'bearer_static':
+      // token_enc should be decrypted server-side before reaching tests;
+      // in test context, use the PLAINTEXT token from environment variable.
+      return { Authorization: `Bearer ${process.env['API_TEST_BEARER_TOKEN'] ?? ''}` };
+    case 'api_key':
+      return { [profile.headerName]: process.env['API_TEST_API_KEY'] ?? '' };
+    case 'basic': {
+      const creds = Buffer.from(
+        `${profile.username}:${process.env['API_TEST_PASSWORD'] ?? ''}`,
+      ).toString('base64');
+      return { Authorization: `Basic ${creds}` };
+    }
+    default:
+      return {};
+  }
+}

package/src/lib/assertions.ts

@@ -0,0 +1,79 @@
+import { expect } from '@playwright/test';
+import type { APIResponse } from '@playwright/test';
+
+/**
+ * Assert HTTP status code with a descriptive failure message.
+ * Prefers this over raw expect(res.status()).toBe(N) so failures show the response body.
+ */
+export async function assertStatus(
+  response: APIResponse,
+  expectedStatus: number,
+): Promise<void> {
+  if (response.status() !== expectedStatus) {
+    let body = '<no body>';
+    try {
+      body = await response.text();
+    } catch { /* ignore */ }
+    expect(
+      response.status(),
+      `Expected HTTP ${expectedStatus} but got ${response.status()}.\nBody: ${body.slice(0, 500)}`,
+    ).toBe(expectedStatus);
+  }
+}
+
+/**
+ * Assert that the response body matches a JSON schema shape.
+ * Checks required top-level keys and their types.
+ */
+export async function assertJsonShape(
+  response: APIResponse,
+  shape: Record<string, 'string' | 'number' | 'boolean' | 'object' | 'array'>,
+): Promise<void> {
+  const json = await response.json();
+  for (const [key, type] of Object.entries(shape)) {
+    expect(json, `Response missing key "${key}"`).toHaveProperty(key);
+    if (type === 'array') {
+      expect(Array.isArray(json[key]), `Expected "${key}" to be an array`).toBe(true);
+    } else {
+      expect(typeof json[key], `Expected "${key}" to be "${type}"`).toBe(type);
+    }
+  }
+}
+
+/**
+ * Assert that security headers are present on an API response.
+ * API8: Security Misconfiguration check.
+ */
+export function assertSecurityHeaders(response: APIResponse): void {
+  const headers = response.headers();
+  expect(headers['x-content-type-options'], 'Missing X-Content-Type-Options').toBe('nosniff');
+  const frameOptions = headers['x-frame-options'];
+  expect(
+    frameOptions === 'DENY' || frameOptions === 'SAMEORIGIN',
+    `X-Frame-Options should be DENY or SAMEORIGIN, got "${frameOptions}"`,
+  ).toBe(true);
+  expect(headers['strict-transport-security'], 'Missing Strict-Transport-Security').toBeTruthy();
+  expect(headers['content-security-policy'], 'Missing Content-Security-Policy').toBeTruthy();
+}
+
+/**
+ * Assert that no sensitive fields are exposed in a JSON response.
+ * API8 / Sensitive Data Exposure check.
+ */
+export async function assertNoSensitiveFields(response: APIResponse): Promise<void> {
+  const sensitiveFields = ['password', 'secret', 'token', 'access_token', 'private_key', 'cvv', 'ssn'];
+  let json: unknown;
+  try {
+    json = await response.json();
+  } catch {
+    return; // non-JSON response — skip
+  }
+  const text = JSON.stringify(json).toLowerCase();
+  for (const field of sensitiveFields) {
+    const pattern = new RegExp(`"${field}"\\s*:\\s*"[^"]{4,}"`, 'i');
+    expect(
+      pattern.test(text),
+      `Response body appears to contain sensitive field "${field}"`,
+    ).toBe(false);
+  }
+}

package/src/lib/cleanup-registry.ts

@@ -0,0 +1,36 @@
+/**
+ * Tracks async cleanup callbacks so they can be run in LIFO order after a test
+ * completes — even if the test fails.
+ *
+ * Usage:
+ *   const cleanup = new CleanupRegistry();
+ *   cleanup.register(async () => client.delete(`/users/${id}`));
+ *   // In afterAll/afterEach: await cleanup.run();
+ */
+export class CleanupRegistry {
+  private callbacks: Array<() => Promise<void>> = [];
+
+  /** Register an async cleanup callback. Callbacks run in reverse order. */
+  register(callback: () => Promise<void>): void {
+    this.callbacks.push(callback);
+  }
+
+  /** Run all registered callbacks in LIFO order. Logs failures but does not throw. */
+  async run(): Promise<void> {
+    const toClean = [...this.callbacks].reverse();
+    this.callbacks = [];
+
+    for (const cb of toClean) {
+      try {
+        await cb();
+      } catch (err) {
+        console.warn(`[CleanupRegistry] Cleanup callback failed: ${(err as Error).message}`);
+      }
+    }
+  }
+
+  /** Number of pending cleanup callbacks. */
+  get size(): number {
+    return this.callbacks.length;
+  }
+}

package/src/lib/environment-guard.ts

@@ -0,0 +1,46 @@
+/**
+ * Environment guard for MUTATING and LOAD_SENSITIVE tests.
+ *
+ * MUTATING tests must never run against production without explicit bypass.
+ * Call assertNotProduction() at the start of any MUTATING test's beforeAll/beforeEach.
+ */
+
+const PRODUCTION_IDENTIFIERS = ['prod', 'production', 'live'];
+
+export function assertNotProduction(): void {
+  const env = (process.env.API_TEST_ENV ?? '').toLowerCase();
+  const isProduction = PRODUCTION_IDENTIFIERS.some((id) => env.includes(id));
+  if (isProduction) {
+    const bypass = process.env.API_TEST_ALLOW_MUTATING_ON_PROD === 'true';
+    if (!bypass) {
+      throw new Error(
+        `ENVIRONMENT_GUARD: MUTATING tests cannot run against production environment "${env}". ` +
+        `Set API_TEST_ALLOW_MUTATING_ON_PROD=true to bypass (requires explicit approval).`,
+      );
+    }
+    console.warn(
+      `[EnvironmentGuard] WARNING: MUTATING test running against production environment "${env}". ` +
+      `This was explicitly bypassed with API_TEST_ALLOW_MUTATING_ON_PROD=true.`,
+    );
+  }
+}
+
+export function assertLoadTestsEnabled(): void {
+  if (process.env.API_TEST_ENABLE_LOAD !== 'true') {
+    throw new Error(
+      `LOAD_SENSITIVE tests are disabled by default. ` +
+      `Set API_TEST_ENABLE_LOAD=true to enable load and rate-limit tests.`,
+    );
+  }
+}
+
+export function getBaseUrl(): string {
+  const url = process.env.API_TEST_BASE_URL;
+  if (!url) {
+    throw new Error(
+      'API_TEST_BASE_URL environment variable is not set. ' +
+      'Set it to the base URL of the API under test (e.g. https://staging.api.example.com).',
+    );
+  }
+  return url;
+}

package/src/lib/retry.ts

@@ -0,0 +1,53 @@
+import type { APIResponse } from '@playwright/test';
+
+export interface RetryOptions {
+  maxAttempts: number;
+  retryableStatuses: number[];
+  backoffMs: number[];
+}
+
+const DEFAULT_RETRY_OPTIONS: RetryOptions = {
+  maxAttempts: 3,
+  retryableStatuses: [503, 502, 504],
+  backoffMs: [1000, 3000],
+};
+
+/**
+ * Wraps an API call with retry logic.
+ * Retries only on transient network errors (503, 502, 504) or connection timeouts.
+ * Never retries on 4xx — those are genuine test failures.
+ */
+export async function withRetry(
+  fn: () => Promise<APIResponse>,
+  options: Partial<RetryOptions> = {},
+): Promise<APIResponse> {
+  const opts = { ...DEFAULT_RETRY_OPTIONS, ...options };
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt < opts.maxAttempts; attempt++) {
+    try {
+      const response = await fn();
+      if (opts.retryableStatuses.includes(response.status()) && attempt < opts.maxAttempts - 1) {
+        const delay = opts.backoffMs[attempt] ?? opts.backoffMs[opts.backoffMs.length - 1];
+        await sleep(delay);
+        continue;
+      }
+      return response;
+    } catch (err: any) {
+      lastError = err;
+      const isTransient =
+        err?.message?.includes('ECONNRESET') ||
+        err?.message?.includes('ECONNREFUSED') ||
+        err?.message?.includes('timeout');
+      if (!isTransient || attempt >= opts.maxAttempts - 1) throw err;
+      const delay = opts.backoffMs[attempt] ?? opts.backoffMs[opts.backoffMs.length - 1];
+      await sleep(delay);
+    }
+  }
+
+  throw lastError ?? new Error('Retry exhausted with no response');
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/specs/auth.api.spec.ts

@@ -0,0 +1,112 @@
+import { test, expect } from '@playwright/test';
+import { BaseApiClient } from '../lib/api-client.js';
+import { assertStatus, assertJsonShape, assertNoSensitiveFields } from '../lib/assertions.js';
+import { CleanupRegistry } from '../lib/cleanup-registry.js';
+import { withRetry } from '../lib/retry.js';
+import { getBaseUrl, assertNotProduction } from '../lib/environment-guard.js';
+
+/**
+ * Authentication and Authorization API tests.
+ *
+ * @tag @safe tests: read-only, safe to run anywhere
+ * @tag @mutating tests: create/delete resources — assertNotProduction() called first
+ * @tag @security tests: deliberate invalid/malformed auth attempts
+ */
+test.describe('@safe Authentication — happy paths', () => {
+  let client: BaseApiClient;
+
+  test.beforeAll(async ({ playwright }) => {
+    client = BaseApiClient.create({
+      request: await playwright.request.newContext({ baseURL: getBaseUrl() }),
+      bearerToken: process.env.API_TEST_BEARER_TOKEN,
+    });
+  });
+
+  test.afterAll(async () => {
+    await client.dispose();
+  });
+
+  test('authenticated request returns 200 not 401', async () => {
+    const result = await client.get('/projects');
+    assertStatus(result, 200);
+  });
+
+  test('response body contains no plaintext secrets', async () => {
+    const result = await client.get('/projects');
+    assertStatus(result, 200);
+    assertNoSensitiveFields(result);
+  });
+});
+
+test.describe('@security Authentication — negative paths', () => {
+  let anonClient: BaseApiClient;
+
+  test.beforeAll(async ({ playwright }) => {
+    anonClient = BaseApiClient.create({
+      request: await playwright.request.newContext({ baseURL: getBaseUrl() }),
+      // no token — anonymous
+    });
+  });
+
+  test.afterAll(async () => {
+    await anonClient.dispose();
+  });
+
+  test('missing auth returns 401', async () => {
+    const result = await anonClient.get('/projects');
+    assertStatus(result, 401);
+  });
+
+  test('invalid bearer token returns 401', async ({ playwright }) => {
+    const badClient = BaseApiClient.create({
+      request: await playwright.request.newContext({ baseURL: getBaseUrl() }),
+      bearerToken: 'invalid-token-abc123',
+    });
+    const result = await badClient.get('/projects');
+    assertStatus(result, 401);
+    await badClient.dispose();
+  });
+});
+
+test.describe('@mutating Auth Profile CRUD', () => {
+  let client: BaseApiClient;
+  const cleanup = new CleanupRegistry();
+
+  test.beforeAll(async ({ playwright }) => {
+    assertNotProduction();
+    client = BaseApiClient.create({
+      request: await playwright.request.newContext({ baseURL: getBaseUrl() }),
+      bearerToken: process.env.API_TEST_BEARER_TOKEN,
+    });
+  });
+
+  test.afterAll(async () => {
+    await cleanup.run();
+    await client.dispose();
+  });
+
+  test('create and delete a bearer_static auth profile', async () => {
+    const projectId = process.env.API_TEST_PROJECT_ID ?? 'test-project-id';
+
+    const created = await withRetry(() =>
+      client.post(`/projects/${projectId}/api-spec/auth-profiles`, {
+        type: 'bearer_static',
+        name: 'Test Bearer Profile',
+        token: 'test-token-abc123',
+      })
+    );
+    assertStatus(created, 200);
+    const body = await created.json();
+    expect(body.id).toBeTruthy();
+
+    cleanup.register(async () => {
+      await client.delete(`/projects/${projectId}/api-spec/auth-profiles/${body.id}`);
+    });
+
+    // Verify masked in GET response
+    const fetched = await client.get(`/projects/${projectId}/api-spec/auth-profiles/${body.id}`);
+    assertStatus(fetched, 200);
+    const fetchedBody = await fetched.json();
+    expect(fetchedBody.token_enc).toBe('***');
+  });
+});

package/src/specs/smoke.api.spec.ts

@@ -0,0 +1,28 @@
+import { test, expect } from '@playwright/test';
+import { BaseApiClient } from '../lib/api-client.js';
+import { assertStatus, assertSecurityHeaders } from '../lib/assertions.js';
+import { getBaseUrl, assertNotProduction } from '../lib/environment-guard.js';
+
+test.describe('@safe Smoke', () => {
+  let client: BaseApiClient;
+
+  test.beforeAll(async ({ playwright }) => {
+    client = BaseApiClient.create({
+      request: await playwright.request.newContext({ baseURL: getBaseUrl() }),
+    });
+  });
+
+  test.afterAll(async () => {
+    await client.dispose();
+  });
+
+  test('GET /health returns 200', async () => {
+    const result = await client.get('/health');
+    assertStatus(result, 200);
+  });
+
+  test('API returns security headers', async () => {
+    const result = await client.get('/health');
+    assertSecurityHeaders(result);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "paths": {
+      "@playwright/test": ["../../node_modules/playwright/test.d.ts"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test-results"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.