@prodverdict/engine 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export type { Finding, CheckResult, Verdict, Severity, ContractType, ProdVerdictError } from './types.js';
+export { isProdVerdictError } from './types.js';
+export { parseConfigFile, validateConfig } from './config/index.js';
+export type { ProdVerdictConfig, AccessContractConfig, ConfigContractConfig, ConfigRule } from './config/index.js';
+export type { StripeReader, StripeSubscription, DatabaseReader, AppUser } from './connectors/index.js';
+export { createLiveStripeReader, createLivePostgresReader, createFixtureStripeReader, createFixtureDatabaseReader, loadFixtureSubscriptions, loadFixtureUsers, defaultFixturePaths, assertSqlIdentifier, assertSqlIdentifiers } from './connectors/index.js';
+export type { FixturePaths } from './connectors/index.js';
+export { evaluateAccess } from './evaluators/access.js';
+export type { AccessDataSources } from './evaluators/access.js';
+export { evaluateConfig, scanEnvReferences, parseEnvFile } from './evaluators/config.js';
+export type { ConfigDataSources } from './evaluators/config.js';
+export { aggregateVerdict } from './verdict.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC1G,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACpE,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACnH,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACvG,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7P,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,YAAY,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACzF,YAAY,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { isProdVerdictError } from './types.js';
+export { parseConfigFile, validateConfig } from './config/index.js';
+export { createLiveStripeReader, createLivePostgresReader, createFixtureStripeReader, createFixtureDatabaseReader, loadFixtureSubscriptions, loadFixtureUsers, defaultFixturePaths, assertSqlIdentifier, assertSqlIdentifiers } from './connectors/index.js';
+export { evaluateAccess } from './evaluators/access.js';
+export { evaluateConfig, scanEnvReferences, parseEnvFile } from './evaluators/config.js';
+export { aggregateVerdict } from './verdict.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGpE,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE7P,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+export type Severity = 'high' | 'medium' | 'low';
+export type Verdict = 'pass' | 'warn' | 'fail';
+export type ContractType = 'access' | 'config' | 'migration' | 'boundary' | 'restore';
+export interface Finding {
+    contract: ContractType;
+    severity: Severity;
+    /** Namespaced entity identifier, e.g. "user:usr_abc" or "price:price_pro" */
+    entity: string;
+    message: string;
+    fix?: string | undefined;
+}
+export interface CheckResult {
+    contract: ContractType;
+    verdict: Verdict;
+    findings: Finding[];
+    evaluatedAt: string;
+}
+export interface ProdVerdictError extends Error {
+    code: 'CONFIG_INVALID' | 'CONNECTOR_ERROR' | 'UNKNOWN';
+}
+export declare function isProdVerdictError(err: unknown): err is ProdVerdictError;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AACjD,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAC/C,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;AAEtF,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,QAAQ,CAAC;IACnB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAiB,SAAQ,KAAK;IAC7C,IAAI,EAAE,gBAAgB,GAAG,iBAAiB,GAAG,SAAS,CAAC;CACxD;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,gBAAgB,CAExE"}

package/dist/types.js

@@ -0,0 +1,4 @@
+export function isProdVerdictError(err) {
+    return err instanceof Error && 'code' in err;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAwBA,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,OAAO,GAAG,YAAY,KAAK,IAAI,MAAM,IAAI,GAAG,CAAC;AAC/C,CAAC"}

package/dist/verdict.d.ts

@@ -0,0 +1,3 @@
+import type { Finding, Verdict } from './types.js';
+export declare function aggregateVerdict(findings: Finding[]): Verdict;
+//# sourceMappingURL=verdict.d.ts.map

package/dist/verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.d.ts","sourceRoot":"","sources":["../src/verdict.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEnD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAI7D"}

package/dist/verdict.js

@@ -0,0 +1,8 @@
+export function aggregateVerdict(findings) {
+    if (findings.some((f) => f.severity === 'high'))
+        return 'fail';
+    if (findings.some((f) => f.severity === 'medium' || f.severity === 'low'))
+        return 'warn';
+    return 'pass';
+}
+//# sourceMappingURL=verdict.js.map

package/dist/verdict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.js","sourceRoot":"","sources":["../src/verdict.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,gBAAgB,CAAC,QAAmB;IAClD,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IAC/D,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,QAAQ,KAAK,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IACzF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@prodverdict/engine",
+  "version": "0.0.1",
+  "description": "Core evaluation engine for ProdVerdict production contracts",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prodv-dev/prodverdict-sdk.git",
+    "directory": "packages/engine"
+  },
+  "homepage": "https://github.com/prodv-dev/prodverdict-sdk#readme",
+  "keywords": ["prodverdict", "production-contracts", "stripe", "saas", "access-control"],
+  "scripts": {
+    "prebuild": "node -e \"try{require('fs').unlinkSync('tsconfig.tsbuildinfo')}catch(e){}\"",
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "stripe": "^16.0.0",
+    "pg": "^8.12.0",
+    "yaml": "^2.4.5",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.11.6"
+  }
+}

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export { parseConfigFile, validateConfig } from './parse.js';
+export { ProdVerdictConfigSchema, type ProdVerdictConfig, type AccessContractConfig, type ConfigContractConfig, type ConfigRule } from './schema.js';

package/src/config/parse.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { validateConfig } from './parse.js';
+
+const validRaw = {
+  version: 1,
+  contracts: [
+    {
+      type: 'access',
+      source_of_truth: 'stripe',
+      database: { url_env: 'DATABASE_URL' },
+      stripe: { secret_env: 'STRIPE_SECRET_KEY' },
+      plans: { price_pro: 'pro', price_starter: 'starter' },
+      severity: 'high',
+      fix: 'Sync has_paid_access from webhooks.',
+    },
+  ],
+};
+
+describe('validateConfig', () => {
+  it('accepts a valid config', () => {
+    const cfg = validateConfig(validRaw);
+    expect(cfg.version).toBe(1);
+    expect(cfg.contracts[0]?.type).toBe('access');
+  });
+
+  it('applies default column names', () => {
+    const cfg = validateConfig(validRaw);
+    const db = cfg.contracts[0]!.database;
+    expect(db.columns.id).toBe('id');
+    expect(db.columns.has_paid_access).toBe('has_paid_access');
+  });
+
+  it('applies default users_table', () => {
+    const cfg = validateConfig(validRaw);
+    expect(cfg.contracts[0]!.database.users_table).toBe('users');
+  });
+
+  it('rejects wrong version', () => {
+    expect(() => validateConfig({ ...validRaw, version: 2 })).toThrow('prodverdict.yml is invalid');
+  });
+
+  it('rejects missing contracts', () => {
+    expect(() => validateConfig({ version: 1 })).toThrow('prodverdict.yml is invalid');
+  });
+
+  it('rejects empty contracts array', () => {
+    expect(() => validateConfig({ version: 1, contracts: [] })).toThrow('prodverdict.yml is invalid');
+  });
+
+  it('rejects missing stripe.secret_env', () => {
+    const raw = structuredClone(validRaw);
+    // @ts-expect-error intentional invalid input
+    delete raw.contracts[0].stripe.secret_env;
+    expect(() => validateConfig(raw)).toThrow('prodverdict.yml is invalid');
+  });
+
+  it('rejects missing database.url_env', () => {
+    const raw = structuredClone(validRaw);
+    // @ts-expect-error intentional invalid input
+    delete raw.contracts[0].database.url_env;
+    expect(() => validateConfig(raw)).toThrow('prodverdict.yml is invalid');
+  });
+});

package/src/config/parse.ts

@@ -0,0 +1,48 @@
+import { readFileSync } from 'fs';
+import { parse as parseYaml } from 'yaml';
+import { ZodError } from 'zod';
+import { ProdVerdictConfigSchema, type ProdVerdictConfig } from './schema.js';
+
+function makeConfigError(message: string): Error & { code: 'CONFIG_INVALID' } {
+  const err = new Error(message) as Error & { code: 'CONFIG_INVALID' };
+  err.code = 'CONFIG_INVALID';
+  return err;
+}
+
+export function validateConfig(raw: unknown): ProdVerdictConfig {
+  const result = ProdVerdictConfigSchema.safeParse(raw);
+  if (!result.success) {
+    throw makeConfigError(formatZodError(result.error));
+  }
+  return result.data;
+}
+
+export function parseConfigFile(filePath: string): ProdVerdictConfig {
+  let text: string;
+  try {
+    text = readFileSync(filePath, 'utf8');
+  } catch (err) {
+    throw makeConfigError(
+      `Cannot read config file at "${filePath}": ${String(err)}`,
+    );
+  }
+
+  let raw: unknown;
+  try {
+    raw = parseYaml(text);
+  } catch (err) {
+    throw makeConfigError(
+      `Failed to parse YAML in "${filePath}": ${String(err)}`,
+    );
+  }
+
+  return validateConfig(raw);
+}
+
+function formatZodError(err: ZodError): string {
+  const lines = err.issues.map((issue) => {
+    const path = issue.path.join('.') || '(root)';
+    return `  ${path}: ${issue.message}`;
+  });
+  return `prodverdict.yml is invalid:\n${lines.join('\n')}`;
+}

package/src/config/schema.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+
+const SeveritySchema = z.enum(['high', 'medium', 'low']);
+
+const AccessDatabaseSchema = z.object({
+  url_env: z.string().min(1).describe('Name of the env var holding DATABASE_URL'),
+  users_table: z.string().min(1).default('users'),
+  columns: z
+    .object({
+      id: z.string().default('id'),
+      stripe_customer_id: z.string().default('stripe_customer_id'),
+      has_paid_access: z.string().default('has_paid_access'),
+      plan: z.string().default('plan'),
+    })
+    .default({}),
+});
+
+const AccessStripeSchema = z.object({
+  secret_env: z.string().min(1).describe('Name of the env var holding STRIPE_SECRET_KEY'),
+});
+
+const AccessContractSchema = z.object({
+  type: z.literal('access'),
+  source_of_truth: z.literal('stripe').default('stripe'),
+  database: AccessDatabaseSchema,
+  stripe: AccessStripeSchema,
+  /** Map of Stripe price ID -> plan slug used in the app */
+  plans: z.record(z.string(), z.string()).optional(),
+  /** Default severity applied to findings if not overridden per-rule */
+  severity: SeveritySchema.default('high'),
+  /** Default human/agent-readable fix hint */
+  fix: z.string().optional(),
+});
+
+export type AccessContractConfig = z.infer<typeof AccessContractSchema>;
+
+// ── Config Contract ────────────────────────────────────────────────────────────
+
+const ConfigRuleSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('required'),
+    name: z.string().min(1),
+    description: z.string().optional(),
+    severity: SeveritySchema.optional(),
+  }),
+  z.object({
+    type: z.literal('not_default'),
+    name: z.string().min(1),
+    forbidden_values: z.array(z.string()).min(1),
+    severity: SeveritySchema.optional(),
+  }),
+]);
+
+export type ConfigRule = z.infer<typeof ConfigRuleSchema>;
+
+const ConfigContractSchema = z.object({
+  type: z.literal('config'),
+  /** Default severity for findings */
+  severity: SeveritySchema.default('high'),
+  /** Explicit rules about individual env vars */
+  rules: z.array(ConfigRuleSchema).default([]),
+  /** Scan source code for process.env.* references and check against .env.example */
+  scan_references: z.boolean().default(true),
+  /** Path to the env example file (relative to repo root) */
+  env_example_file: z.string().default('.env.example'),
+  /** Warn if a required var's value looks like a placeholder */
+  check_placeholders: z.boolean().default(true),
+  /** Variable names to ignore during reference scan */
+  ignore_vars: z.array(z.string()).default([]),
+});
+
+export type ConfigContractConfig = z.infer<typeof ConfigContractSchema>;
+
+// ── Union ──────────────────────────────────────────────────────────────────────
+
+const ContractSchema = z.discriminatedUnion('type', [AccessContractSchema, ConfigContractSchema]);
+
+export const ProdVerdictConfigSchema = z.object({
+  version: z.literal(1),
+  contracts: z.array(ContractSchema).min(1),
+});
+
+export type ProdVerdictConfig = z.infer<typeof ProdVerdictConfigSchema>;

package/src/connectors/fixture.ts

@@ -0,0 +1,18 @@
+import type { StripeReader, StripeSubscription, DatabaseReader, AppUser } from './types.js';
+
+/** In-memory connectors for testing — accepts pre-loaded data */
+export function createFixtureStripeReader(subscriptions: StripeSubscription[]): StripeReader {
+  return {
+    async listSubscriptions() {
+      return subscriptions;
+    },
+  };
+}
+
+export function createFixtureDatabaseReader(users: AppUser[]): DatabaseReader {
+  return {
+    async listUsers() {
+      return users;
+    },
+  };
+}

package/src/connectors/index.ts

@@ -0,0 +1,7 @@
+export type { StripeReader, StripeSubscription, DatabaseReader, AppUser } from './types.js';
+export { createLiveStripeReader } from './stripe-live.js';
+export { createLivePostgresReader } from './postgres-live.js';
+export { createFixtureStripeReader, createFixtureDatabaseReader } from './fixture.js';
+export { loadFixtureSubscriptions, loadFixtureUsers, defaultFixturePaths } from './load-fixtures.js';
+export type { FixturePaths } from './load-fixtures.js';
+export { assertSqlIdentifier, assertSqlIdentifiers } from './sql-identifiers.js';

package/src/connectors/load-fixtures.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from 'vitest';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { loadFixtureSubscriptions, loadFixtureUsers, defaultFixturePaths } from './load-fixtures.js';
+
+const fixturesDir = join(dirname(fileURLToPath(import.meta.url)), '../../../../fixtures');
+
+describe('load-fixtures', () => {
+  it('loads stripe and db fixture JSON', () => {
+    const paths = defaultFixturePaths(fixturesDir);
+    const subs = loadFixtureSubscriptions(paths.stripeSubscriptions);
+    const users = loadFixtureUsers(paths.dbUsers);
+
+    expect(subs).toHaveLength(2);
+    expect(users).toHaveLength(2);
+    expect(subs[0]?.customerId).toBe('cus_fixture_active');
+    expect(users[0]?.hasPaidAccess).toBe(true);
+  });
+});

package/src/connectors/load-fixtures.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import type { StripeSubscription, AppUser } from './types.js';
+
+export interface FixturePaths {
+  stripeSubscriptions: string;
+  dbUsers: string;
+}
+
+export function loadFixtureSubscriptions(filePath: string): StripeSubscription[] {
+  const raw = JSON.parse(readFileSync(filePath, 'utf8')) as Array<{
+    id: string;
+    customerId: string;
+    status: string;
+    priceIds: string[];
+  }>;
+  return raw.map((item) => ({
+    id: item.id,
+    customerId: item.customerId,
+    status: item.status,
+    priceIds: item.priceIds,
+  }));
+}
+
+export function loadFixtureUsers(filePath: string): AppUser[] {
+  const raw = JSON.parse(readFileSync(filePath, 'utf8')) as Array<{
+    id: string;
+    stripe_customer_id: string | null;
+    has_paid_access: boolean;
+    plan: string | null;
+  }>;
+  return raw.map((row) => ({
+    id: row.id,
+    stripeCustomerId: row.stripe_customer_id,
+    hasPaidAccess: row.has_paid_access,
+    plan: row.plan,
+  }));
+}
+
+export function defaultFixturePaths(fixturesDir: string): FixturePaths {
+  return {
+    stripeSubscriptions: join(fixturesDir, 'stripe', 'subscriptions.json'),
+    dbUsers: join(fixturesDir, 'db', 'users.json'),
+  };
+}

package/src/connectors/postgres-live.ts

@@ -0,0 +1,61 @@
+import pg from 'pg';
+import type { DatabaseReader, AppUser } from './types.js';
+import type { AccessContractConfig } from '../config/schema.js';
+import { assertSqlIdentifier, assertSqlIdentifiers } from './sql-identifiers.js';
+
+function makeConnectorError(message: string): Error & { code: 'CONNECTOR_ERROR' } {
+  const err = new Error(message) as Error & { code: 'CONNECTOR_ERROR' };
+  err.code = 'CONNECTOR_ERROR';
+  return err;
+}
+
+export function createLivePostgresReader(cfg: AccessContractConfig): DatabaseReader {
+  const connectionString = process.env[cfg.database.url_env];
+  if (!connectionString) {
+    throw makeConnectorError(
+      `Missing required env var "${cfg.database.url_env}" for database connector. ` +
+        'Provide a read-only database connection string.',
+    );
+  }
+
+  const cols = cfg.database.columns;
+  const table = cfg.database.users_table;
+  assertSqlIdentifier(table, 'database.users_table');
+  assertSqlIdentifiers(cols, 'database.columns');
+
+  const pool = new pg.Pool({ connectionString, max: 2 });
+  let closed = false;
+
+  return {
+    async listUsers(): Promise<AppUser[]> {
+      if (closed) {
+        throw makeConnectorError('Database reader is closed.');
+      }
+
+      let client: pg.PoolClient | undefined;
+      try {
+        client = await pool.connect();
+        const res = await client.query(
+          `SELECT ${cols.id}, ${cols.stripe_customer_id}, ${cols.has_paid_access}, ${cols.plan} FROM ${table}`,
+        );
+        return res.rows.map((row): AppUser => ({
+          id: String(row[cols.id]),
+          stripeCustomerId: row[cols.stripe_customer_id] as string | null,
+          hasPaidAccess: Boolean(row[cols.has_paid_access]),
+          plan: row[cols.plan] as string | null,
+        }));
+      } catch (err) {
+        throw makeConnectorError(`Database query failed: ${String(err)}`);
+      } finally {
+        client?.release();
+      }
+    },
+
+    async close(): Promise<void> {
+      if (!closed) {
+        closed = true;
+        await pool.end();
+      }
+    },
+  };
+}

package/src/connectors/sql-identifiers.test.ts

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+import { assertSqlIdentifier } from './sql-identifiers.js';
+
+describe('assertSqlIdentifier', () => {
+  it('accepts valid identifiers', () => {
+    expect(() => assertSqlIdentifier('users', 'table')).not.toThrow();
+    expect(() => assertSqlIdentifier('has_paid_access', 'column')).not.toThrow();
+  });
+
+  it('rejects invalid identifiers', () => {
+    expect(() => assertSqlIdentifier('users; DROP TABLE', 'table')).toThrow(/Invalid SQL identifier/);
+    expect(() => assertSqlIdentifier('1users', 'table')).toThrow(/Invalid SQL identifier/);
+  });
+});

package/src/connectors/sql-identifiers.ts

@@ -0,0 +1,16 @@
+/** Matches safe Postgres identifiers for table/column names from config */
+const SQL_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+export function assertSqlIdentifier(value: string, label: string): void {
+  if (!SQL_IDENTIFIER.test(value)) {
+    throw new Error(
+      `Invalid SQL identifier for ${label}: "${value}". Use only letters, numbers, and underscores.`,
+    );
+  }
+}
+
+export function assertSqlIdentifiers(values: Record<string, string>, labelPrefix: string): void {
+  for (const [key, value] of Object.entries(values)) {
+    assertSqlIdentifier(value, `${labelPrefix}.${key}`);
+  }
+}

package/src/connectors/stripe-live.ts

@@ -0,0 +1,38 @@
+import Stripe from 'stripe';
+import type { StripeReader, StripeSubscription } from './types.js';
+
+function makeConnectorError(message: string): Error & { code: 'CONNECTOR_ERROR' } {
+  const err = new Error(message) as Error & { code: 'CONNECTOR_ERROR' };
+  err.code = 'CONNECTOR_ERROR';
+  return err;
+}
+
+export function createLiveStripeReader(secretKeyEnvVar: string): StripeReader {
+  const key = process.env[secretKeyEnvVar];
+  if (!key) {
+    throw makeConnectorError(
+      `Missing required env var "${secretKeyEnvVar}" for Stripe connector. ` +
+        'Provide a restricted read-only Stripe secret key.',
+    );
+  }
+
+  const client = new Stripe(key, { apiVersion: '2024-06-20' });
+
+  return {
+    async listSubscriptions(): Promise<StripeSubscription[]> {
+      const results: StripeSubscription[] = [];
+      for await (const sub of client.subscriptions.list({ limit: 100 })) {
+        const priceIds = (sub.items?.data ?? [])
+          .map((item) => item.price?.id)
+          .filter((id): id is string => Boolean(id));
+        results.push({
+          id: sub.id,
+          customerId: typeof sub.customer === 'string' ? sub.customer : sub.customer.id,
+          status: sub.status,
+          priceIds,
+        });
+      }
+      return results;
+    },
+  };
+}

package/src/connectors/types.ts

@@ -0,0 +1,25 @@
+/** Minimal Stripe subscription data needed for access evaluation */
+export interface StripeSubscription {
+  id: string;
+  customerId: string;
+  status: string;
+  /** Active price IDs on the subscription (usually one) */
+  priceIds: string[];
+}
+
+export interface StripeReader {
+  listSubscriptions(): Promise<StripeSubscription[]>;
+}
+
+/** Minimal app user row needed for access evaluation */
+export interface AppUser {
+  id: string;
+  stripeCustomerId: string | null;
+  hasPaidAccess: boolean;
+  plan: string | null;
+}
+
+export interface DatabaseReader {
+  listUsers(): Promise<AppUser[]>;
+  close?(): Promise<void>;
+}