backend-skeleton 1.0.0-beta.1

package/handles/providers/typescript-express/plan.mjs

@@ -0,0 +1,234 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// O6-style ambiguity rejection (mirrors java-spring's detectBasePackage / python-fastapi's
+// detectImportRoot): TS/Node has no __init__.py-style package marker, so the project root is the
+// nearest ancestor directory containing BOTH package.json and tsconfig.json among this module's
+// own files. More than one distinct candidate is refused with named candidates, never silently
+// picked. Source root is `<root>/src` if it exists (matches the real oracle's own layout), else
+// the project root itself.
+function projectRootFor(file) {
+	let dir = path.dirname(file);
+	for (;;) {
+		if (fs.existsSync(path.join(dir, 'package.json')) && fs.existsSync(path.join(dir, 'tsconfig.json'))) return dir;
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+function detectProjectRoot(moduleFiles, repoRoot) {
+	const roots = new Set();
+	for (const file of moduleFiles) {
+		const r = projectRootFor(file);
+		if (r) roots.add(r);
+	}
+	if (roots.size === 0) {
+		throw new Error('could not detect a TypeScript project root (no ancestor directory with both package.json and tsconfig.json found above any scanned file for this module).');
+	}
+	if (roots.size > 1) {
+		throw new Error(`ambiguous TypeScript project root -- found ${roots.size} different candidates among this module's own files: ${[...roots].map((r) => path.relative(repoRoot, r)).join(', ')}. This provider doesn't support multi-project-root repos yet.`);
+	}
+	const projectRoot = [...roots][0];
+	const srcRoot = fs.existsSync(path.join(projectRoot, 'src')) ? path.join(projectRoot, 'src') : projectRoot;
+	return { projectRoot, srcRoot };
+}
+
+function listTypeScriptFilesUnder(dir) {
+	const out = [];
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'build') continue;
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) out.push(...listTypeScriptFilesUnder(full));
+		else if (entry.name.endsWith('.ts')) out.push(full);
+	}
+	return out.sort();
+}
+
+// Same "canonical fetch" concept as java-spring's findFetchOperation / python-fastapi's
+// findFetchRoute: a GET endpoint whose path is exactly `${basePath}/:param` (Express's own
+// path-param syntax, optionally regex-constrained -- `:id([0-9]+)`, confirmed in the real oracle)
+// on a controller whose class-name affinity-matches the entity.
+function findFetchRoute(controllers, entityClassName) {
+	const needle = entityClassName.toLowerCase();
+	for (const controller of controllers) {
+		if (!controller.className.toLowerCase().includes(needle)) continue;
+		for (const ep of controller.endpoints) {
+			if (ep.verb !== 'GET') continue;
+			const suffix = ep.path.slice(controller.basePath.length);
+			if (/^\/:[^/(]+(\([^)]*\))?$/.test(suffix)) {
+				return { method: ep.method, path: ep.path, file: controller.file, line: ep.line, controllerClassName: controller.className };
+			}
+		}
+	}
+	return null;
+}
+
+// Resolves an import specifier to a real file on disk, extension-probed the same way Node's own
+// TS resolver would. Relative specifiers (`./x`, `../x`) resolve against `fromFile`'s own
+// directory; bare specifiers (`controllers/users`) resolve against `srcRoot` (this project's own
+// `baseUrl`, confirmed against the real oracle's own tsconfig.json: `"baseUrl": "src/"`).
+function resolveImportSpecifier(fromFile, specifier, srcRoot) {
+	const base = specifier.startsWith('.') ? path.resolve(path.dirname(fromFile), specifier) : path.join(srcRoot, specifier);
+	for (const candidate of [`${base}.ts`, path.join(base, 'index.ts')]) {
+		if (fs.existsSync(candidate)) return candidate;
+	}
+	return null;
+}
+
+// `router.get('/:id(...)', [...], show)` -- `show` is only ever an imported identifier (inline
+// arrow-function handlers are already excluded by the scanner). Resolves the router file's own
+// `import { ..., show, ... } from '<specifier>'`, then follows ONE level of barrel re-export
+// (`export * from './show'`, confirmed in the real oracle's own controllers/users/index.ts) if
+// the resolved file doesn't define `show` itself -- no deeper, matching the existing "narrow, not
+// general" discipline every other cross-file resolution in this codebase already follows.
+function resolveHandlerFile(routerFile, handlerName, srcRoot) {
+	const routerText = fs.readFileSync(routerFile, 'utf8');
+	const importRe = new RegExp(`import\\s*\\{[^}]*\\b${handlerName}\\b[^}]*\\}\\s*from\\s*["']([^"']+)["']`);
+	const importMatch = routerText.match(importRe);
+	if (!importMatch) return null;
+	const directFile = resolveImportSpecifier(routerFile, importMatch[1], srcRoot);
+	if (!directFile) return null;
+
+	const directText = fs.readFileSync(directFile, 'utf8');
+	if (new RegExp(`export\\s+const\\s+${handlerName}\\b`).test(directText)) return directFile;
+
+	// One barrel hop: `export * from './show'` inside an index.ts that doesn't define the handler
+	// itself.
+	for (const m of directText.matchAll(/export\s*\*\s*from\s*["']([^"']+)["']/g)) {
+		const barrelTarget = resolveImportSpecifier(directFile, m[1], srcRoot);
+		if (barrelTarget && new RegExp(`export\\s+const\\s+${handlerName}\\b`).test(fs.readFileSync(barrelTarget, 'utf8'))) {
+			return barrelTarget;
+		}
+	}
+	return null;
+}
+
+// The oracle's own only real protection against leaking a column the app never otherwise exposes
+// (e.g. a password hash): a hand-written `select: [...]` allow-list literal in the fetch handler's
+// own `findOne(...)`/`find(...)` call -- TypeORM's real `{ select: false }` column option exists
+// but the oracle doesn't use it, so requiring a Java/Python-style `<Entity>Public` convention this
+// ecosystem's own real code doesn't demonstrate would be inventing a requirement, not grounding
+// one. Required, not decorative -- mirrors D-fastapi-adapter's own `<Entity>Public` precondition
+// in spirit exactly.
+function findSelectAllowList(handlerFile) {
+	if (!handlerFile) return null;
+	const text = fs.readFileSync(handlerFile, 'utf8');
+	const m = text.match(/select\s*:\s*\[([^\]]*)\]/);
+	if (!m) return null;
+	const fields = m[1].split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+	return fields.length > 0 ? fields : null;
+}
+
+// `export const AppDataSource = new DataSource({...})` -- or whatever this app names its own
+// DataSource instance. TypeORM 0.3.x's real, current app-owned-instance API (see
+// D-typescript-express-provider in DECISIONS.md for why this targets DataSource and not the
+// oracle's own stale `getRepository()` global-connection-manager pattern). Same
+// shallowest-then-name deterministic tie-break as python-fastapi's own findSessionDep.
+const DATA_SOURCE_RE = /export\s+const\s+(\w+)\s*=\s*new\s+DataSource\s*\(/;
+
+function findDataSource(files) {
+	const candidates = [];
+	for (const file of files) {
+		const m = fs.readFileSync(file, 'utf8').match(DATA_SOURCE_RE);
+		if (m) candidates.push({ file, name: m[1] });
+	}
+	if (candidates.length === 0) return null;
+	candidates.sort((a, b) => {
+		const depthA = a.file.split(path.sep).length;
+		const depthB = b.file.split(path.sep).length;
+		return depthA !== depthB ? depthA - depthB : a.file.localeCompare(b.file);
+	});
+	return candidates[0];
+}
+
+function dottedModulePath(file, srcRoot) {
+	const rel = path.relative(srcRoot, file).replace(/\.ts$/, '');
+	return rel.split(path.sep).join('/');
+}
+
+// The descriptor-facing entry point (handles/providers/typescript-express.mjs's provider.plan).
+// See schemas/handles-plan.schema.json for the sbf.handles-plan/1 envelope this returns.
+export function plan({ repoRoot, scanReport, module: moduleName, resourceFilter }) {
+	const targetModule = moduleName
+		? scanReport.related_modules.find((m) => m.module === moduleName)
+		: scanReport.related_modules[0];
+
+	if (!targetModule) {
+		return {
+			schema: 'sbf.handles-plan/1', provider: 'typescript-express', module: null, resources: [],
+			notes: ['no related module in the scan report -- run `bskel scan` first, or pass --module explicitly'],
+		};
+	}
+
+	const moduleFiles = [...targetModule.controllers.map((c) => c.file), ...targetModule.entities.map((e) => e.file)].filter(Boolean);
+	const { projectRoot, srcRoot } = detectProjectRoot(moduleFiles, repoRoot);
+	const allProjectFiles = listTypeScriptFilesUnder(srcRoot);
+	const dataSource = findDataSource(allProjectFiles);
+
+	const resources = [];
+	const notes = [];
+
+	for (const entity of targetModule.entities) {
+		if (resourceFilter && !resourceFilter.includes(entity.className)) continue;
+		const fetchRoute = findFetchRoute(targetModule.controllers, entity.className);
+		const handlerFile = fetchRoute ? resolveHandlerFile(fetchRoute.file, fetchRoute.method, srcRoot) : null;
+		const selectFields = handlerFile ? findSelectAllowList(handlerFile) : null;
+
+		if (!fetchRoute) {
+			notes.push(`${entity.className}: no single-resource GET route found on a router whose name contains "${entity.className}" -- fetch() will need to be hand-written`);
+		} else if (!handlerFile) {
+			notes.push(`${entity.className}: could not resolve ${fetchRoute.method}'s own defining file (import, or one barrel hop, from ${path.relative(repoRoot, fetchRoute.file)}) -- resolver NOT generated.`);
+		} else if (!selectFields) {
+			notes.push(`${entity.className}: no literal select: [...] allow-list found in ${path.relative(repoRoot, handlerFile)} -- resolver NOT generated (a generic handle-fetch route serializing the raw entity could leak a column the app never otherwise exposes, e.g. a password hash). Add one and re-run.`);
+		}
+		if (fetchRoute && !entity.idField) {
+			notes.push(`${entity.className}: no primary-key field detected on the entity -- resolver NOT generated.`);
+		} else if (fetchRoute && entity.idField && !entity.idFieldIsUuid) {
+			// This handle system's own token format (kind:type:UUID[:pointer]) can only ever address a
+			// UUID-shaped resource identifier -- an entity whose primary key is the TypeORM default
+			// (an auto-incrementing integer, @PrimaryGeneratedColumn() with no argument) genuinely
+			// cannot be reached through a handle at all, a structural fact about this whole project's
+			// handle scheme, not a TypeScript-specific limitation. Found live via a real `tsc --noEmit`
+			// type error (the real oracle's own User entity uses the integer form) before this
+			// distinction was tracked.
+			notes.push(`${entity.className}: primary key "${entity.idField}" is not UUID-typed (@PrimaryGeneratedColumn('uuid')) -- resolver NOT generated. This project's handle format can only address UUID-shaped resource identifiers.`);
+		}
+		if (fetchRoute && handlerFile && selectFields && entity.idField && entity.idFieldIsUuid && !dataSource) {
+			notes.push(`${entity.className}: fetch route and select allow-list found, but no "export const X = new DataSource(...)" was found anywhere under ${path.relative(repoRoot, srcRoot)}/ -- resolver NOT generated. (This provider targets TypeORM's current DataSource API, not the older global getRepository() pattern.)`);
+		}
+		if (fetchRoute) {
+			notes.push(`${entity.className}: static scanning cannot safely determine this route's real authorization logic (see ${path.relative(repoRoot, fetchRoute.file)}:${fetchRoute.line}) -- the generated resolver's checkAccess() always denies until hand-wired.`);
+		}
+
+		const willGenerateResolver = Boolean(fetchRoute && handlerFile && selectFields && entity.idField && entity.idFieldIsUuid && dataSource);
+
+		resources.push({
+			type: entity.className,
+			table: entity.table,
+			idField: entity.idField,
+			readPath: fetchRoute ? `dataSource.getRepository(${entity.className}).findOne({ where: { ${entity.idField}: resourceUid } })` : null,
+			requiredAuthority: 'TODO_ACCESS_CHECK',
+			willGenerateResolver,
+			// provider-specific extras (additionalProperties: true in schemas/handles-plan.schema.json)
+			fetchRoute,
+			selectFields,
+			modelImport: dottedModulePath(entity.file, srcRoot),
+			dataSource,
+		});
+	}
+
+	if (resources.length === 0) {
+		notes.push(`no entities found for module "${targetModule.module}" ${resourceFilter ? `matching --resource filter [${resourceFilter.join(', ')}]` : ''} -- nothing to plan.`);
+	}
+
+	return {
+		schema: 'sbf.handles-plan/1',
+		provider: 'typescript-express',
+		projectRoot,
+		srcRoot,
+		module: targetModule.module,
+		resources,
+		notes,
+	};
+}

package/handles/providers/typescript-express/templates/codec.ts.tmpl

@@ -0,0 +1,116 @@
+// Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate,
+// or the JS/Java/Python/TypeScript implementations will silently diverge.
+//
+// Encodes/decodes backend-skeleton "handles" (kind:type:uuid[:pointer], base64url with an
+// "sbf1_" prefix). Must stay behavior-identical to handles/codec.mjs (the JS reference
+// implementation) -- verified by an executed round-trip test (test/handles-typescript-codec.
+// test.mjs), not just inspection. See D-typescript-express-provider in DECISIONS.md.
+//
+// A SELF-CONTAINED port, not an `import` of this CLI's own handles/codec.mjs -- importing this
+// whole scaffolding tool into a generated file would make it a runtime dependency of the target
+// application, architecturally wrong regardless of same-ecosystem convenience. Zero imports
+// beyond node:crypto. Zero non-erasable TypeScript syntax (no decorators, no enums with values)
+// so this file runs directly via `node --experimental-strip-types` with no tsc/devDependency
+// needed for behavioral verification -- real type-checking is proven separately (a real
+// `tsc --noEmit`), not by this file's own runtime test.
+import { createHash } from 'node:crypto';
+
+export const NS_SBF_FIELD = 'a3f1c2e0-8b4d-4f1a-9c3e-1d2b3a4c5d6e';
+
+const UUID_RE = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+const HANDLE_RE = new RegExp(`^([rfo]):([^:]+):(${UUID_RE})(?::(.*))?$`, 'i');
+// D-security-10 parity: Node's own `Buffer.from(str, 'base64')` silently discards characters
+// outside the base64 alphabet instead of rejecting them (the same runtime this whole CLI already
+// runs on -- not a new investigation, confirmed by the JS reference's own identical guard).
+const BASE64URL_CHARSET_RE = /^[A-Za-z0-9_-]*$/;
+
+const MAX_HANDLE_TOKEN_LENGTH = 2048;
+
+export interface DecodedHandle {
+  kind: string;
+  type: string;
+  uuid: string;
+  pointer: string | null;
+}
+
+function base64url(buf: Buffer): string {
+  return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function base64urlDecode(str: string): Buffer {
+  if (!BASE64URL_CHARSET_RE.test(str)) {
+    throw new Error('not valid base64url after the sbf1_ prefix');
+  }
+  const pad = (4 - (str.length % 4)) % 4;
+  const padded = str.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat(pad);
+  return Buffer.from(padded, 'base64');
+}
+
+export function encodeHandle(kind: string, type: string, uuid: string, pointer: string | null = null): string {
+  if (!['r', 'f', 'o'].includes(kind)) throw new Error(`invalid handle kind "${kind}" (expected r, f, or o)`);
+  if (!type || !uuid) throw new Error('encodeHandle requires both type and uuid');
+  if (kind === 'f' && !pointer) throw new Error('field handles (kind=f) require a JSON Pointer');
+  if (kind !== 'f' && pointer) throw new Error(`handle kind "${kind}" must not carry a JSON Pointer (only kind=f field handles do)`);
+  const raw = `${kind}:${type}:${uuid}${pointer ? `:${pointer}` : ''}`;
+  return `sbf1_${base64url(Buffer.from(raw, 'utf8'))}`;
+}
+
+export function decodeHandle(token: string): DecodedHandle {
+  if (typeof token !== 'string' || !token.startsWith('sbf1_')) {
+    throw new Error('not an sbf1 handle (missing "sbf1_" prefix)');
+  }
+  if (token.length > MAX_HANDLE_TOKEN_LENGTH) {
+    throw new Error(`handle token exceeds the maximum length of ${MAX_HANDLE_TOKEN_LENGTH} characters`);
+  }
+  const raw = base64urlDecode(token.slice('sbf1_'.length)).toString('utf8');
+  const match = raw.match(HANDLE_RE);
+  if (!match) throw new Error(`malformed handle payload after decoding: "${raw}"`);
+  const [, kind, type, uuid, pointer] = match;
+  return { kind: kind.toLowerCase(), type, uuid: uuid.toLowerCase(), pointer: pointer ?? null };
+}
+
+function uuidToBytes(uuid: string): Buffer {
+  return Buffer.from(uuid.replace(/-/g, ''), 'hex');
+}
+
+function bytesToUuid(bytes: Buffer): string {
+  const hex = bytes.toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/** RFC 4122 UUIDv5 (name-based, SHA-1). */
+export function uuidv5(namespaceUuid: string, name: string): string {
+  const hash = createHash('sha1')
+    .update(Buffer.concat([uuidToBytes(namespaceUuid), Buffer.from(name, 'utf8')]))
+    .digest();
+  const bytes = Buffer.from(hash.subarray(0, 16));
+  bytes[6] = (bytes[6] & 0x0f) | 0x50; // version 5
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant RFC 4122
+  return bytesToUuid(bytes);
+}
+
+export function deriveHandleUid(kind: string, type: string, uuid: string, pointer: string | null): string {
+  if (kind === 'r') return uuid;
+  if (kind === 'f') {
+    if (!pointer) throw new Error('field handles require a pointer to derive handle_uid');
+    return uuidv5(NS_SBF_FIELD, `${type}:${uuid}:${pointer}`);
+  }
+  if (kind === 'o') return uuidv5(NS_SBF_FIELD, `${type}:${uuid}:o`);
+  throw new Error(`invalid handle kind "${kind}"`);
+}
+
+// RFC 6901 JSON Pointer resolution. Unlike the Python port (which needed a `_MISSING` sentinel
+// because Python's plain `dict.get()` conflates "absent" with a genuine `None`), TypeScript/
+// JavaScript already has the exact distinction the JS reference relies on -- `undefined` (absent)
+// vs `null` (present, empty) -- so this is a direct, unmodified port.
+export function resolveJsonPointer(obj: unknown, pointer: string | null): unknown {
+  if (pointer == null || pointer === '') return obj;
+  if (!pointer.startsWith('/')) throw new Error(`invalid JSON Pointer "${pointer}" -- must start with "/"`);
+  const parts = pointer.split('/').slice(1).map((p) => p.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current == null) return undefined;
+    current = Array.isArray(current) ? (current as unknown[])[Number(part)] : (current as Record<string, unknown>)[part];
+  }
+  return current;
+}

package/handles/providers/typescript-express/templates/registry.ts.tmpl

@@ -0,0 +1,39 @@
+// Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.
+//
+// In-process registry mapping a handle `type` string to its resolver instance -- deliberately NOT
+// a database table. This 1st-slice scope carries no recover()/snapshot lifecycle equivalent (no
+// sbf_handle/sbf_handle_snapshot table) -- mirrors java-spring/python-fastapi's own pre-O4/
+// pre-follow-up state, not a gap specific to this provider. See D-typescript-express-provider in
+// DECISIONS.md.
+
+// Unlike the Python provider's ResourceResolver (which threads a per-request SQLAlchemy `session`
+// through every method, matching FastAPI's own dependency-injection convention), this interface
+// takes NO dataSource/session parameter at all -- TypeORM's `DataSource` is an app-wide singleton
+// instantiated once at startup (`export const AppDataSource = new DataSource(...)`), not a
+// per-request-injected object the way SQLAlchemy's `Session` is. Each generated resolver imports
+// its own DataSource reference directly (see resolver.ts.tmpl) -- a genuine simplification from
+// this ecosystem's own real pattern, not an arbitrary deviation from the Python provider's shape.
+export interface ResourceResolver {
+  type: string;
+  fetch(resourceUid: string): Promise<unknown>;
+  checkAccess(obj: unknown): void;
+  patchField(obj: unknown, pointer: string, value: unknown): void;
+  toPublic(obj: unknown): unknown;
+}
+
+// Small, self-contained error classes -- router.ts.tmpl maps these to real HTTP status codes
+// explicitly (403/501), never relying on Express's own default error handler (Express 4, the
+// real oracle's own pinned version, does not auto-catch a rejected Promise inside an async route
+// handler the way Express 5 does -- cannot be assumed of an arbitrary target app either way).
+export class HandleAccessDeniedError extends Error {}
+export class HandleNotImplementedError extends Error {}
+
+const RESOLVERS = new Map<string, ResourceResolver>();
+
+export function register(resolver: ResourceResolver): void {
+  RESOLVERS.set(resolver.type, resolver);
+}
+
+export function resolverFor(type: string): ResourceResolver | undefined {
+  return RESOLVERS.get(type);
+}

package/handles/providers/typescript-express/templates/resolver.ts.tmpl

@@ -0,0 +1,55 @@
+// Generated by backend-skeleton (bskel handles emit) for feature {{FEATURE_ID}}.
+// type = "{{RESOURCE_TYPE}}"
+//
+// `fetch`/`toPublic` are wired to real, existing code: `fetch` uses TypeORM's own DataSource-
+// based `getRepository(...).findOne(...)`, this stack's current (not the deprecated global
+// `getRepository()`) canonical read path, and `toPublic` projects only through the field
+// allow-list found in the real fetch handler's own `select: [...]` literal -- required so a
+// generic handle-fetch route can never accidentally serialize a column the app does not
+// otherwise expose (a real example this provider was built against: a table entity carrying a
+// password hash column with no `{ select: false }` protection of its own). See the fetch route
+// this was planned from: {{FETCH_ROUTE_FILE}}:{{FETCH_ROUTE_LINE}}.
+//
+// `checkAccess` is DELIBERATELY a fail-closed stub, not auto-generated business logic. Express has
+// no imperatively-readable global security context, and this stack's own real authorization logic
+// lives inside route handler bodies (per-row checks) or project-specific middleware (e.g. a
+// `checkRole(...)` convention) -- neither of which a static source scan can safely extract or
+// assume is a stable, framework-level signal. Wire it to whatever this app's own current-user/
+// permission pattern is before relying on it -- until then, every request is denied.
+//
+// `patchField` is DELIBERATELY a stub for the same reason Java's ResourceResolverStub.java.tmpl's
+// patchField() is: this stack's own update conventions must be checked by a human before writing
+// to them (see D-resolver-scope in DECISIONS.md) -- do not write directly against the ORM, that
+// bypasses this app's existing validation and business rules.
+import { {{MODEL}} } from '{{MODEL_IMPORT_PATH}}';
+import { {{DATA_SOURCE_NAME}} } from '{{DATA_SOURCE_IMPORT_PATH}}';
+import { register, HandleAccessDeniedError, HandleNotImplementedError, type ResourceResolver } from '../registry';
+
+const {{RESOURCE_TYPE}}Resolver: ResourceResolver = {
+  type: '{{RESOURCE_TYPE}}',
+
+  async fetch(resourceUid: string): Promise<unknown> {
+    return {{DATA_SOURCE_NAME}}.getRepository({{MODEL}}).findOne({ where: { {{ID_FIELD}}: resourceUid } });
+  },
+
+  checkAccess(_obj: unknown): void {
+    // TODO: wire this app's own current-user/permission check before relying on this resolver.
+    // Fails closed until then -- every request is denied, not silently permitted.
+    throw new HandleAccessDeniedError('access check not yet implemented for {{RESOURCE_TYPE}}');
+  },
+
+  patchField(_obj: unknown, pointer: string, _value: unknown): void {
+    // TODO: route through this app's real update path for {{MODEL}}, matching whichever
+    // partial-update convention its own real update handler actually uses. Do not write directly
+    // to the entity's own fields and save -- that bypasses this app's existing validation and
+    // business rules.
+    throw new HandleNotImplementedError(`patchField not yet implemented for {{RESOURCE_TYPE}}${pointer}`);
+  },
+
+  toPublic(obj: unknown): unknown {
+    const row = obj as Record<string, unknown>;
+    return { {{SELECT_PROJECTION}} };
+  },
+};
+
+register({{RESOURCE_TYPE}}Resolver);

package/handles/providers/typescript-express/templates/resolvers_index.ts.tmpl

@@ -0,0 +1,11 @@
+// Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.
+//
+// Imports every resolver module under this directory for its `register(...)` side effect. Unlike
+// the Python provider's own resolvers_init.py.tmpl (which uses `pkgutil.iter_modules` at RUNTIME
+// and is therefore truly feature-independent content), Node ESM has no direct equivalent without
+// extra tooling -- this file's own import list is regenerated by `bskel handles emit` from the
+// resolvers directory's real current contents every run (including any orphaned resolver a
+// feature no longer plans but that O2's own "never delete, only report" policy leaves on disk),
+// so it stays correct without a human ever hand-editing it, even though its content is not
+// literally static the way the Python file's is.
+{{IMPORTS}}

package/handles/providers/typescript-express/templates/router.ts.tmpl

@@ -0,0 +1,122 @@
+// Generated by backend-skeleton.
+//
+// D-handles (DECISIONS.md): exposed in production. Per-resolver `checkAccess()` is the entire
+// defense for this generic-object-accessor security surface -- see the docstring on each
+// generated resolver for why it is ALWAYS a fail-closed stub in this provider.
+//
+// Every async handler body is wrapped in an explicit try/catch, never relying on Express's own
+// default error handling -- Express 4 (the real community boilerplate this provider was verified
+// against still pins this version) does NOT auto-catch a rejected Promise inside an async route
+// handler the way Express 5 does, and that can't be assumed of an arbitrary target app either way.
+import { Router, type Request, type Response } from 'express';
+import { decodeHandle, resolveJsonPointer } from './codec';
+import { resolverFor, HandleAccessDeniedError, HandleNotImplementedError } from './registry';
+
+export const router = Router();
+
+router.get('/handles/:handle', async (req: Request, res: Response) => {
+  // Express's own types allow a route param to be `string | string[]` (repeated wildcard
+  // segments can produce an array) -- a single named `:handle` segment never actually does in
+  // practice, but `decodeHandle` only accepts a real string, so this is checked explicitly
+  // rather than silently asserted.
+  if (typeof req.params.handle !== 'string') {
+    res.status(400).json({ detail: 'malformed handle path segment' });
+    return;
+  }
+  let decoded;
+  try {
+    decoded = decodeHandle(req.params.handle);
+  } catch (exc) {
+    res.status(400).json({ detail: (exc as Error).message });
+    return;
+  }
+
+  const resolver = resolverFor(decoded.type);
+  if (!resolver) {
+    res.status(404).json({ detail: `no resolver registered for handle type "${decoded.type}"` });
+    return;
+  }
+
+  try {
+    const obj = await resolver.fetch(decoded.uuid);
+    if (obj == null) {
+      res.status(404).json({ detail: 'resource not found' });
+      return;
+    }
+    resolver.checkAccess(obj);
+    const publicObj = resolver.toPublic(obj);
+    if (decoded.pointer == null) {
+      res.status(200).json(publicObj);
+      return;
+    }
+    // Walks the PUBLIC projection, not the raw fetch() row -- a deliberate, security-preserving
+    // departure, not a shortcut: this provider's own fetch() returns the raw entity, and
+    // toPublic() is a SEPARATE, required projection specifically because a real entity can carry
+    // a column (e.g. a password hash) with no protection besides the handler's own select
+    // allow-list. Walking the raw row here would silently reopen exactly that leak vector.
+    const target = resolveJsonPointer(publicObj, decoded.pointer);
+    if (target === undefined) {
+      res.status(404).json({ detail: `pointer "${decoded.pointer}" does not resolve on ${decoded.type}` });
+      return;
+    }
+    res.status(200).json(target as object);
+  } catch (exc) {
+    if (exc instanceof HandleAccessDeniedError) {
+      res.status(403).json({ detail: exc.message });
+      return;
+    }
+    throw exc;
+  }
+});
+
+router.patch('/handles/:handle', async (req: Request, res: Response) => {
+  // Express's own types allow a route param to be `string | string[]` (repeated wildcard
+  // segments can produce an array) -- a single named `:handle` segment never actually does in
+  // practice, but `decodeHandle` only accepts a real string, so this is checked explicitly
+  // rather than silently asserted.
+  if (typeof req.params.handle !== 'string') {
+    res.status(400).json({ detail: 'malformed handle path segment' });
+    return;
+  }
+  let decoded;
+  try {
+    decoded = decodeHandle(req.params.handle);
+  } catch (exc) {
+    res.status(400).json({ detail: (exc as Error).message });
+    return;
+  }
+
+  // D-security-10 parity: checks kind explicitly, not just pointer-presence -- mirrors
+  // HandleController.java.tmpl's/router.py.tmpl's identical check.
+  if (decoded.kind !== 'f' || decoded.pointer == null) {
+    res.status(400).json({ detail: 'cannot PATCH a resource-level handle (kind=r) -- only field handles (kind=f) support PATCH' });
+    return;
+  }
+
+  const resolver = resolverFor(decoded.type);
+  if (!resolver) {
+    res.status(404).json({ detail: `no resolver registered for handle type "${decoded.type}"` });
+    return;
+  }
+
+  try {
+    const obj = await resolver.fetch(decoded.uuid);
+    if (obj == null) {
+      res.status(404).json({ detail: 'resource not found' });
+      return;
+    }
+    resolver.checkAccess(obj);
+    resolver.patchField(obj, decoded.pointer, req.body);
+    res.status(204).send();
+  } catch (exc) {
+    if (exc instanceof HandleAccessDeniedError) {
+      res.status(403).json({ detail: exc.message });
+      return;
+    }
+    if (exc instanceof HandleNotImplementedError) {
+      res.status(501).json({ detail: exc.message });
+      return;
+    }
+    throw exc;
+  }
+});

package/handles/providers/typescript-express.mjs

@@ -0,0 +1,20 @@
+import { plan } from './typescript-express/plan.mjs';
+import { emitTypeScriptExpress } from './typescript-express/emit.mjs';
+
+// G5 (D-typescript-express-provider). Zero-registration descriptor loaded by handles/registry.mjs
+// -- see schemas/handles-provider.schema.json for the contract this object's JSON-shaped fields
+// must match (plan/emit are functions, checked separately).
+export const provider = {
+	contract: 'sbf.handles-provider/1',
+	id: 'typescript-express',
+	title: 'TypeScript / Express / TypeORM',
+	requiresCapabilities: ['resource.fetch'],
+	// No migration.sql -- this 1st-slice provider generates no schema-owning artifact (no
+	// recover(), no sbf_handle table), matching java-spring/python-fastapi's own pre-O4/
+	// pre-follow-up state, not a gap specific to this provider.
+	outputs: { spec: [] },
+	plan,
+	emit(args) {
+		return emitTypeScriptExpress(args);
+	},
+};