@starci/hfs 5.1.0 → 5.3.0

package/runtime/scripts/hfs/architecture/identity.mjs

@@ -1,57 +1,17 @@
-// identity.mjs - the back-end identity machine. Under lite the one token verifier is be.integrations.passport: jose's jwtVerify
-// there checks the app's OWN key set (createLocalJWKSet over the keys it signs with, never createRemoteJWKSet), pins issuer,
-// audience and algorithms, and no file decodes a token unverified or reads authorization claims from a request body (R329).
-// In both editions every jwtVerify call holds the JWT policy (R260, jwtPolicyProblems).
+// identity.mjs - the back-end identity machine. Under lite the one token verifier is @starci/auth, composed by be.integrations.passport:
+// no app file calls jose's jwtVerify, decodes a token unverified or reads authorization claims from a request body (R329), and the
+// passport integration imports @starci/auth/server. In both editions every jwtVerify call holds the JWT policy (R260, jwtPolicyProblems).
 import path from 'node:path';
 import { machineKit } from './machine-ast.mjs';
-import { fromConfig, importedFrom, jwtPolicyProblems, reportAt, unwrap } from './jwt-ast.mjs';
+import { jwtPolicyProblems, reportAt, unwrap } from './jwt-ast.mjs';
 import { accessName } from '../../lib/ts-ast.mjs';
 const PASSPORT_SLOT = 'be.integrations.passport';
+const PACKAGE_ENTRY = '@starci/auth/server';
 const BE_JWT_VERIFIED = 'BE_AUTH_JWT_OWN_JWKS';
 /** The rule ids the back-end identity machine reports. */
 export const IDENTITY_RULE_IDS = Object.freeze(['BE_AUTH_JWT_OWN_JWKS', 'BE_JWT_ALG_PINNED']);
 const JWT_MODULES = new Set(['jose', 'jsonwebtoken', 'jwt-decode']);
 const CLAIM_NAMES = new Set(['role', 'roles', 'membership', 'memberships']);
-const objectLiteral = (kit, checker, node) => {
-    const current = unwrap(kit.ts, node);
-    if (!current)
-        return null;
-    if (kit.ts.isObjectLiteralExpression(current))
-        return current;
-    if (!kit.ts.isIdentifier(current))
-        return null;
-    for (const declaration of kit.declarationsOf(checker, current)) {
-        if (kit.ts.isVariableDeclaration(declaration) && declaration.initializer) {
-            const value = unwrap(kit.ts, declaration.initializer);
-            if (kit.ts.isObjectLiteralExpression(value))
-                return value;
-        }
-    }
-    return null;
-};
-const staticStrings = (kit, checker, node) => {
-    const current = unwrap(kit.ts, node);
-    if (kit.ts.isStringLiteralLike(current))
-        return [current.text];
-    if (kit.ts.isArrayLiteralExpression(current)) {
-        const literals = current.elements.filter((element) => kit.ts.isStringLiteralLike(element));
-        if (literals.length === current.elements.length)
-            return literals.map((element) => element.text);
-    }
-    const value = kit.stringValue(checker, current);
-    return value === null ? null : [value];
-};
-const jwksArgument = (kit, checker, node) => {
-    const current = unwrap(kit.ts, node);
-    if (!current)
-        return false;
-    if (kit.ts.isCallExpression(current))
-        return importedFrom(kit, checker, current.expression, new Set(['jose']), new Set(['createLocalJWKSet']));
-    if (!kit.ts.isIdentifier(current))
-        return false;
-    return kit.declarationsOf(checker, current).some((declaration) => kit.ts.isVariableDeclaration(declaration) && declaration.initializer
-        && jwksArgument(kit, checker, declaration.initializer));
-};
 const importedCall = (kit, checker, call) => {
     const direct = kit.importBinding(checker, call.expression);
     if (direct?.module === 'jwt-decode' && direct.name === 'default')
@@ -84,41 +44,16 @@ const fromRequestBody = (kit, checker, node, seen = new Set()) => {
     return kit.declarationsOf(checker, current).some(declaration => kit.ts.isVariableDeclaration(declaration) && declaration.initializer
         && fromRequestBody(kit, checker, declaration.initializer, seen));
 };
-function verifyJwtCall(kit, checker, file, node, counters, violations) {
-    counters.verifyCalls += 1;
-    if (file.slot !== PASSPORT_SLOT) {
-        reportAt(violations, kit, BE_JWT_VERIFIED, file, node, `jwtVerify is called outside ${PASSPORT_SLOT}; the integration is the one token verifier.`);
-        return true;
-    }
-    const options = objectLiteral(kit, checker, node.arguments[2]);
-    const property = (name) => options ? kit.propertyOf(options, name) : null;
-    const values = (name) => {
-        const entry = property(name);
-        return entry ? staticStrings(kit, checker, kit.valueOfProperty(entry)) : null;
-    };
-    const issuer = property('issuer');
-    const audience = values('audience');
-    const algorithms = values('algorithms');
-    // The audience is pinned by a literal or, as R260 accepts, by typed configuration (the skeleton's TokenOptions.audience).
-    const audienceEntry = property('audience');
-    const pinnedAudience = (audience !== null && audience.length > 0)
-        || (audienceEntry != null && fromConfig(kit.ts, checker, kit.valueOfProperty(audienceEntry)));
-    const good = jwksArgument(kit, checker, node.arguments[1]) && issuer != null && pinnedAudience
-        && algorithms !== null && algorithms.length > 0;
-    if (!good) {
-        reportAt(violations, kit, BE_JWT_VERIFIED, file, node, 'jwtVerify must check the app\'s own key set (createLocalJWKSet(...) over the keys integrations/passport signs with) and pin issuer, audience and a non-empty algorithms list; jwtVerify then enforces signature and exp.');
-    }
-    else
-        counters.verifiedCalls += 1;
-    return false;
-}
 function inspectJwtCall(kit, checker, file, node, counters, violations) {
     const binding = importedCall(kit, checker, node);
     if (binding && JWT_MODULES.has(binding.module) && ['decode', 'decodeJwt', 'jwtDecode'].includes(binding.name)) {
         reportAt(violations, kit, BE_JWT_VERIFIED, file, node, `${binding.module}.${binding.name} decodes a token without proving its signature; verify it through integrations/passport.`, { module: binding.module, method: binding.name });
     }
-    if (binding?.module === 'jose' && binding.name === 'jwtVerify')
-        return verifyJwtCall(kit, checker, file, node, counters, violations);
+    if (binding?.module === 'jose' && binding.name === 'jwtVerify') {
+        counters.verifyCalls += 1;
+        reportAt(violations, kit, BE_JWT_VERIFIED, file, node, 'jwtVerify is called in the app; @starci/auth verifies the own access tokens, reached through ' + PASSPORT_SLOT + '.');
+        return true;
+    }
     return false;
 }
 function inspectRequestClaims(kit, file, node, checker, violations) {
@@ -146,18 +81,18 @@ function checkOwnJwks(input) {
     const violations = [];
     const integrations = [...input.graph.files.values()].filter((file) => file.slot === PASSPORT_SLOT);
     if (!integrations.length)
-        return { violations, coverage: { status: 'not-applicable', integrationFiles: 0, verifiedCalls: 0 } };
-    const counters = { verifyCalls: 0, verifiedCalls: 0 };
+        return { violations, coverage: { status: 'not-applicable', integrationFiles: 0, verifyCalls: 0 } };
+    const counters = { verifyCalls: 0 };
     for (const file of input.graph.files.values()) {
         const checker = kit.checkerOf(file.sourceFile);
         kit.walk(file.sourceFile, (node) => inspectBackendNode(kit, checker, file, node, counters, violations));
     }
-    if (counters.verifyCalls === 0) {
-        const anchor = integrations.find((file) => path.posix.basename(file.rel).endsWith('.tokens.ts')) ?? integrations[0];
-        if (anchor)
-            reportAt(violations, kit, BE_JWT_VERIFIED, anchor, anchor.sourceFile, `${PASSPORT_SLOT} has no jose.jwtVerify call backed by createLocalJWKSet over the app's own keys.`);
-    }
-    return { violations, coverage: { status: 'checked', integrationFiles: integrations.length, verifyCalls: counters.verifyCalls, verifiedCalls: counters.verifiedCalls } };
+    const composes = integrations.some((file) => file.sourceFile.statements.some((statement) => kit.ts.isImportDeclaration(statement)
+        && kit.ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === PACKAGE_ENTRY));
+    const anchor = integrations.find((file) => path.posix.basename(file.rel) === 'index.ts') ?? integrations[0];
+    if (!composes && anchor)
+        reportAt(violations, kit, BE_JWT_VERIFIED, anchor, anchor.sourceFile, PASSPORT_SLOT + ' does not import ' + PACKAGE_ENTRY + ', the one verifier of the own access tokens.');
+    return { violations, coverage: { status: 'checked', integrationFiles: integrations.length, verifyCalls: counters.verifyCalls, composesPackage: composes } };
 }
 /** R260 BE_JWT_ALG_PINNED: every jose jwtVerify call pins a literal secure algorithm list and a configured issuer, and binds the principal by a configured audience or the authenticated role. */
 export function checkJwtPolicy(input) {

package/runtime/scripts/hfs/architecture/module-per-transport.d.mts

@@ -9,7 +9,7 @@ import type { MachineContext } from './machine-ast.mjs';
  *
  *   - a `*.module.ts` file below a transport folder other than `<f>-<protocol>.module.ts`, a `*.module-definition.ts` that is
  *     not the sibling of the application module or of the transport module of its own folder, and an `@Module` class (or a
- *     `ConfigurableModuleBuilder`/`ConfigurableModuleClass` use) in a feature file that is neither the application module, the
+ *     `ConfigurableModuleBuilder`/`ConfigurableModuleClass` use or a `defineConfigurableModule`/`defineCapabilityModule` call of `@starci/nest-kit`) in a feature file that is neither the application module, the
  *     transport module of its own folder nor that module's definition are refused;
  *   - apps import only transport modules, of the kinds their app kind allows: the `composedBy` list of each transport slot
  *     in knowledge/hfs/slots.yaml (api: graphql, http, websocket; worker: schedule, message). An app root (app.module.ts

package/runtime/scripts/hfs/architecture/module-per-transport.mjs

@@ -11,7 +11,7 @@ import { trimTrailingSlashes } from '../trailing-slashes.mjs';
  *
  *   - a `*.module.ts` file below a transport folder other than `<f>-<protocol>.module.ts`, a `*.module-definition.ts` that is
  *     not the sibling of the application module or of the transport module of its own folder, and an `@Module` class (or a
- *     `ConfigurableModuleBuilder`/`ConfigurableModuleClass` use) in a feature file that is neither the application module, the
+ *     `ConfigurableModuleBuilder`/`ConfigurableModuleClass` use or a `defineConfigurableModule`/`defineCapabilityModule` call of `@starci/nest-kit`) in a feature file that is neither the application module, the
  *     transport module of its own folder nor that module's definition are refused;
  *   - apps import only transport modules, of the kinds their app kind allows: the `composedBy` list of each transport slot
  *     in knowledge/hfs/slots.yaml (api: graphql, http, websocket; worker: schedule, message). An app root (app.module.ts
@@ -99,6 +99,8 @@ function reportModuleClassLocation(file, name, place, composedModuleOf, report)
     if (file.rel !== own)
         report(file, name, `${name.text} is a Nest module declared in ${file.rel}; a feature declares exactly its application module (${place.feature}.module.ts) and one module per transport folder (${place.feature}-<protocol>.module.ts), never a module per operation.`, { feature: place.feature });
 }
+/** The module-definition helpers of @starci/nest-kit: each builds the definition of one module, like `ConfigurableModuleBuilder`. */
+const DEFINITION_HELPERS = ['defineConfigurableModule', 'defineCapabilityModule'];
 function reportConfigurableModuleUses(file, checker, kit, ts, place, env) {
     const own = ownModuleOf(place, file.rel, env.composedModuleOf);
     const isDefinition = file.rel === definitionOf(own);
@@ -106,6 +108,9 @@ function reportConfigurableModuleUses(file, checker, kit, ts, place, env) {
         if (ts.isNewExpression(node) && kit.isImportOf(checker, node.expression, 'ConfigurableModuleBuilder', '@nestjs/common') && !isDefinition) {
             env.report(file, node, `ConfigurableModuleBuilder builds the module definition of one module; in feature ${place.feature} it is written only in ${path.posix.basename(definitionOf(own))}, beside ${path.posix.basename(own)}.`, { feature: place.feature });
         }
+        else if (ts.isCallExpression(node) && !isDefinition && DEFINITION_HELPERS.some(name => kit.isImportOf(checker, node.expression, name, '@starci/nest-kit'))) {
+            env.report(file, node, `${node.expression.getText(file.sourceFile)} builds the module definition of one module; in feature ${place.feature} it is written only in ${path.posix.basename(definitionOf(own))}, beside ${path.posix.basename(own)}.`, { feature: place.feature });
+        }
         else if (ts.isHeritageClause(node) && file.rel !== own) {
             for (const type of node.types)
                 if (kit.isImportOf(checker, type.expression, 'ConfigurableModuleClass', '@nestjs/common')) {

package/runtime/scripts/hfs/architecture/root-packages.d.mts

@@ -0,0 +1,26 @@
+/**
+ * A workspace package of the app root: a first-party package that both sides import through its package entry points and never past
+ * them. `root` is the real path of its folder, `relative` the folder from the app root, `exports` the `exports` of its manifest.
+ */
+export interface RootPackage {
+    root: string;
+    relative: string;
+    name: string;
+    exports: unknown;
+    manifest: Record<string, unknown>;
+    workspace: true;
+    app: false;
+}
+/** The slots whose directories at the app root are first-party packages of the app (agent SDK, module packages, the managed registry). */
+export declare const ROOT_PACKAGE_SLOTS: ReadonlySet<string>;
+/** A package folder with a regular package.json (a link is not one). */
+export declare function packageDirectory(absolute: string): boolean;
+/** The folders the `workspaces` of the app root's package.json name that no side owns, as absolute paths in code-unit order. */
+export declare function rootWorkspaceDirectories(packageRoot: string): string[];
+/**
+ * The record of one package folder of the app root, or null when it is no named package inside the app root.
+ * `canonical` is the file-identity function of the caller (the real path), so a record agrees with the files the graph reads.
+ */
+export declare function rootPackageRecord(packageRoot: string, directory: string, canonical: (file: string) => string): RootPackage | null;
+/** The names of the workspace packages of the app root: what the back-end canon must not read as third-party libraries. */
+export declare function rootPackageNames(packageRoot: string): Set<string>;

package/runtime/scripts/hfs/architecture/root-packages.mjs

@@ -0,0 +1,78 @@
+// root-packages.mjs - the workspace packages of an app ROOT (packages/agent-sdk, packages/module-<name>, the managed packages/modules).
+// They lie outside both side folders and belong to no side; both sides import them by package name, through their package entry points
+// (the `exports` of the manifest), so the import graph reads them as first-party packages and the back-end canon never reads them as
+// a third-party library. The app root's one package.json lists them in `workspaces`; the patterns that start with a side folder
+// (`fe/apps/*`) are that side's own workspaces and are not read here.
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJsonFile as readJson } from '../../lib/json.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
+import { isInside } from '../../lib/walk.mjs';
+import { slash } from '../../lib/path-key.mjs';
+/** The slots whose directories at the app root are first-party packages of the app (agent SDK, module packages, the managed registry). */
+export const ROOT_PACKAGE_SLOTS = new Set(['app.packages', 'app.module-registry']);
+const SIDE_PREFIX = /^(?:be|fe)\//;
+/** A workspace pattern this reader expands (a literal path, or `*` as a whole segment); the others are judged by the workspace rules. */
+const expandablePattern = (written) => !path.isAbsolute(written) && written.split('/').every(segment => segment !== '..' && (!segment.includes('*') || segment === '*'));
+function expandSegment(base, segment) {
+    if (segment !== '*')
+        return [path.join(base, segment)];
+    if (!fs.existsSync(base) || !fs.lstatSync(base).isDirectory())
+        return [];
+    return fs.readdirSync(base, { withFileTypes: true }).filter(item => item.isDirectory()).sort((a, b) => byCodeUnit(a.name, b.name)).map(item => path.join(base, item.name));
+}
+/** A package folder with a regular package.json (a link is not one). */
+export function packageDirectory(absolute) {
+    try {
+        if (!fs.lstatSync(absolute).isDirectory())
+            return false;
+        const manifest = fs.lstatSync(path.join(absolute, 'package.json'));
+        return manifest.isFile() && !manifest.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/** The folders the `workspaces` of the app root's package.json name that no side owns, as absolute paths in code-unit order. */
+export function rootWorkspaceDirectories(packageRoot) {
+    const manifest = readJson(path.join(packageRoot, 'package.json'));
+    const declared = manifest?.workspaces;
+    const patterns = Array.isArray(declared) ? declared : declared?.packages;
+    const found = new Set();
+    for (const pattern of Array.isArray(patterns) ? patterns : []) {
+        if (typeof pattern !== 'string' || !pattern.trim())
+            continue;
+        const written = slash(pattern.trim()).replace(/^\.\//, '');
+        if (SIDE_PREFIX.test(written) || !expandablePattern(written))
+            continue;
+        let bases = [packageRoot];
+        for (const segment of written.split('/'))
+            bases = bases.flatMap(base => expandSegment(base, segment));
+        for (const base of bases)
+            found.add(path.resolve(base));
+    }
+    return [...found].sort(byCodeUnit);
+}
+/**
+ * The record of one package folder of the app root, or null when it is no named package inside the app root.
+ * `canonical` is the file-identity function of the caller (the real path), so a record agrees with the files the graph reads.
+ */
+export function rootPackageRecord(packageRoot, directory, canonical) {
+    if (!packageDirectory(directory) || !isInside(packageRoot, directory))
+        return null;
+    const manifest = readJson(path.join(directory, 'package.json'));
+    const name = manifest?.['name'];
+    if (manifest === null || typeof name !== 'string' || !name)
+        return null;
+    return { root: canonical(directory), relative: slash(path.relative(packageRoot, directory)), name, exports: manifest['exports'], manifest, workspace: true, app: false };
+}
+/** The names of the workspace packages of the app root: what the back-end canon must not read as third-party libraries. */
+export function rootPackageNames(packageRoot) {
+    const names = new Set();
+    for (const directory of rootWorkspaceDirectories(packageRoot)) {
+        const record = rootPackageRecord(packageRoot, directory, (file) => file);
+        if (record !== null)
+            names.add(record.name);
+    }
+    return names;
+}

package/runtime/scripts/hfs/architecture/transport-owner.d.mts

@@ -15,8 +15,7 @@ import type { ArchitectureViolation, CheckInput } from './hfs-graph.mjs';
  *   - no file outside the client folder and the stream reader folder (`fe.transport.stream`, `modules/api/sse/clients/`) references the global `fetch`: a call, `globalThis.fetch`, `window.fetch`, or a
  *     reference passed as a value (`useSWR(key, fetch)`, `const send = fetch`), all of which a spelling-based rule misses; with no
  *     client at all every such reference is a finding that says the repository has no client;
- *   - axios is imported only by the api owner (modules/api, the api package) for its rest calls and by the auth door
- *     (modules/auth/auth-door.ts) for the app's own auth doors; every other HTTP library is a
+ *   - axios is imported only by the api owner (modules/api, the api package) for its rest calls; every other HTTP library is a
  *     second transport wherever it is imported, by static import, `import()` or `require()`;
  *   - an `ApolloClient` is constructed only inside the client folder;
  *   - every GraphQL operation (`graphql/queries/query-*.ts`, `graphql/mutations/mutation-*.ts`, `graphql/subscriptions/subscription-*.ts`) imports the client (or the api

package/runtime/scripts/hfs/architecture/transport-owner.mjs

@@ -17,8 +17,7 @@ import { propertyValue } from './function-spec-providers.mjs';
  *   - no file outside the client folder and the stream reader folder (`fe.transport.stream`, `modules/api/sse/clients/`) references the global `fetch`: a call, `globalThis.fetch`, `window.fetch`, or a
  *     reference passed as a value (`useSWR(key, fetch)`, `const send = fetch`), all of which a spelling-based rule misses; with no
  *     client at all every such reference is a finding that says the repository has no client;
- *   - axios is imported only by the api owner (modules/api, the api package) for its rest calls and by the auth door
- *     (modules/auth/auth-door.ts) for the app's own auth doors; every other HTTP library is a
+ *   - axios is imported only by the api owner (modules/api, the api package) for its rest calls; every other HTTP library is a
  *     second transport wherever it is imported, by static import, `import()` or `require()`;
  *   - an `ApolloClient` is constructed only inside the client folder;
  *   - every GraphQL operation (`graphql/queries/query-*.ts`, `graphql/mutations/mutation-*.ts`, `graphql/subscriptions/subscription-*.ts`) imports the client (or the api
@@ -105,17 +104,15 @@ function isApolloClientConstruction(ts, kit, checker, node) {
     const binding = kit.importBinding(checker, node.expression);
     return Boolean(binding?.name === 'ApolloClient' && binding.module.startsWith('@apollo/client'));
 }
-/** The one auth door of the session issuer's client (`modules/auth/auth-door.ts`, slot fe.modules.auth): it calls the app's own auth doors with axios. */
-const isAuthDoor = (file) => file.slot === 'fe.modules.auth' && path.posix.basename(file.rel) === 'auth-door.ts';
 function inspectLibraryImport({ ts, file, node, transport, report }) {
     const specifier = moduleSpecifierOf(ts, node);
     if (!specifier || !ts.isStringLiteralLike(specifier))
         return;
     const library = specifier.text.split('/')[0];
-    if (!HTTP_LIBRARIES.has(library) || (library === REST_LIBRARY && (API_OWNER_SLOTS.has(file.slot) || isAuthDoor(file))))
+    if (!HTTP_LIBRARIES.has(library) || (library === REST_LIBRARY && (API_OWNER_SLOTS.has(file.slot))))
         return;
     const where = library === REST_LIBRARY
-        ? 'axios belongs to the api owner (modules/api/rest, the api package) and the auth door (modules/auth/auth-door.ts) only: call their functions'
+        ? 'axios belongs to the api owner (modules/api/rest, the api package) only: call their functions'
         : `the transport is Apollo GraphQL (${transport}) with axios for the rest calls of modules/api/rest`;
     report(file, node, `${specifier.text} is a second HTTP transport in ${file.rel}; ${where}.`, { library: specifier.text });
 }

package/runtime/scripts/hfs/architecture/type-context.d.mts

@@ -1,5 +1,5 @@
 import type { CompilerOptions, CreateProgramOptions, Diagnostic, ModuleResolutionCache, ModuleResolutionHost, Node, Program, ProjectReference, SourceFile, TypeChecker } from 'typescript';
-import type { ArchitectureConfig, TypeScriptApi } from './config.mjs';
+import type { ArchitectureConfig, RootPackage, TypeScriptApi } from './config.mjs';
 import type { ProjectRead } from '../typescript-programs.mjs';
 import type { ArchitectureError, ImportEdge, LoadedTypeScript, ModuleReferences, WorkspaceRecord } from './typescript.mjs';
 /** One parsed tsconfig with its compiler program. */
@@ -56,5 +56,8 @@ export interface TypeContextHelpers {
     relativePath(root: string, fileName: string): string;
     packageExported(ts: TypeScriptApi, workspace: WorkspaceRecord, specifier: string, actualTarget: string): boolean;
     boundaryViolation(root: string, edge: ImportEdge, fromWorkspace: WorkspaceRecord | null, toWorkspace: WorkspaceRecord | null, ruleId: string, message: string): ArchitectureError;
+    rootPackageOf(config: Pick<ArchitectureConfig, 'rootPackages'>, specifier: string): RootPackage | null;
+    rootPackageEntryDeclared(item: RootPackage, specifier: string): boolean;
+    rootPackageEntries(item: RootPackage): string[];
 }
 export declare function contextFromProjects(config: ArchitectureConfig, loaded: LoadedTypeScript, paths: string[], helpers: TypeContextHelpers): TypeContext;

package/runtime/scripts/hfs/architecture/type-context.mjs

@@ -241,8 +241,38 @@ function appendEdge(from, sourceFile, project, owningWorkspace, reference, actua
             errors.push(helpers.boundaryViolation(config.root, edge, owningWorkspace, targetWorkspace, 'ARCH_PACKAGE_EXPORT_BYPASS', 'Cross-package imports must use the target package name and a declared package export.'));
     }
 }
+/**
+ * An import of one of the app's root workspace packages (`@scope/agent-sdk`, `@scope/agent-sdk/workbench`). The package lies outside the side
+ * folder, yet it is first-party source both sides may import: through its package entry points (the `exports` of its manifest) and never past
+ * them. An entry point is no import that leaves the side and adds no edge (the package is not part of this side's graph; the package's own
+ * lint judges its files); a path into the package's source is refused. Returns true when the reference was settled here.
+ */
+function rootPackageReference(sourceFile, project, reference, state) {
+    const { config, errors, helpers, host, ts } = state;
+    if (!config.rootPackages?.length)
+        return false;
+    const item = helpers.rootPackageOf(config, reference.specifier);
+    if (item === null)
+        return false;
+    if (!helpers.rootPackageEntryDeclared(item, reference.specifier)) {
+        errors.push({
+            ruleId: 'ARCH_INTERNAL_IMPORT_OUTSIDE',
+            project: project.relative,
+            path: helpers.relativePath(config.root, sourceFile.fileName),
+            ...helpers.sourceLocation(sourceFile, reference.node),
+            specifier: reference.specifier,
+            message: `Internal import ${reference.specifier} reaches into the package ${item.name} past its package entry points; import ${helpers.rootPackageEntries(item).join(', ')} instead.`,
+        });
+        return true;
+    }
+    // An entry point that a path alias sends outside the package is no entry point: the ordinary boundary judges it.
+    const resolved = helpers.resolveTypeScriptModule(ts, reference.specifier, sourceFile.fileName, project.options, host, resolutionCache(state, project));
+    return resolved === undefined || helpers.isInside(item.root, helpers.canonical(resolved));
+}
 function processReference(from, sourceFile, project, owningWorkspace, reference, state) {
     const { config, ts, workspaceNames, workspaces, host, errors, helpers } = state;
+    if (rootPackageReference(sourceFile, project, reference, state))
+        return;
     // A workspace package is read at its source, never at its build: the same import resolves whether or not dist exists.
     const workspaceTarget = workspaces.filter(item => item.root !== helpers.canonical(config.root)).map(item => helpers.workspaceSourceEntry(ts, item, reference.specifier)).find(Boolean);
     const resolvedName = workspaceTarget ?? helpers.resolveTypeScriptModule(ts, reference.specifier, sourceFile.fileName, project.options, host, resolutionCache(state, project));

package/runtime/scripts/hfs/architecture/typescript.d.mts

@@ -1,6 +1,6 @@
 import type { TypeContext } from './type-context.mjs';
 import type { Node, SourceFile, TypeChecker } from 'typescript';
-import type { ArchitectureConfig, TypeScriptApi } from './config.mjs';
+import type { ArchitectureConfig, RootPackage, TypeScriptApi } from './config.mjs';
 export { unwrapExpression } from '../../lib/ts-analysis.mjs';
 /** The target repository's loaded TypeScript: the API, where it resolved from and its version. */
 export interface LoadedTypeScript {
@@ -82,6 +82,12 @@ export declare function exportTargetStrings(value: unknown): string[];
 export declare function workspaceSourceEntry(ts: TypeScriptApi, workspace: WorkspaceRecord, specifier: string): string | null;
 /** Every source file the package.json `exports` of a workspace package maps (each non-wildcard subpath, dist back to source): its public entries. */
 export declare function workspaceExportSources(ts: TypeScriptApi, workspace: WorkspaceRecord): string[];
+/** The root workspace package of the app (`packages/agent-sdk`) a specifier names, its name or a subpath of it; the longest name when several match. */
+export declare function rootPackageOf(config: Pick<ArchitectureConfig, 'rootPackages'>, specifier: string): RootPackage | null;
+/** Whether a specifier into a root package names one of its entry points: a subpath its `exports` declare, or its root through `exports`, `main`/`types` or `src/index`. A path into its source is not an entry point. */
+export declare function rootPackageEntryDeclared(item: RootPackage, specifier: string): boolean;
+/** The subpaths a root package declares for import (`.` first), for the message of a refused deep import. */
+export declare function rootPackageEntries(item: RootPackage): string[];
 /** Parse configured tsconfigs, then build only selected programs and their project-reference closure. */
 export declare function buildTypeScriptContext(config: ArchitectureConfig, injectedTypeScript?: TypeScriptApi | null, paths?: string[]): TypeContext;
 export declare function relativePath(root: string, fileName: string): string;

package/runtime/scripts/hfs/architecture/typescript.mjs

@@ -385,6 +385,26 @@ function packageExported(ts, workspace, specifier, actualTarget) {
         return expected === canonical(actualTarget) || sourceOfTarget(ts, workspace, target) === canonical(actualTarget);
     });
 }
+/** The root workspace package of the app (`packages/agent-sdk`) a specifier names, its name or a subpath of it; the longest name when several match. */
+export function rootPackageOf(config, specifier) {
+    let found = null;
+    for (const item of config.rootPackages ?? [])
+        if (sameOrUnder(specifier, item.name) && (found === null || item.name.length > found.name.length))
+            found = item;
+    return found;
+}
+/** Whether a specifier into a root package names one of its entry points: a subpath its `exports` declare, or its root through `exports`, `main`/`types` or `src/index`. A path into its source is not an entry point. */
+export function rootPackageEntryDeclared(item, specifier) {
+    if (exportCandidates(item, specifier).length > 0)
+        return true;
+    return specifier === item.name && !item.exports && (manifestEntryTargets(item.manifest).length > 0 || packageIndexSource(item) !== null);
+}
+/** The subpaths a root package declares for import (`.` first), for the message of a refused deep import. */
+export function rootPackageEntries(item) {
+    const declaration = item.exports;
+    const keys = declaration && typeof declaration === 'object' && !Array.isArray(declaration) ? Object.keys(declaration).filter(key => key.startsWith('.')) : ['.'];
+    return (keys.length ? keys : ['.']).map(key => (key === '.' ? item.name : `${item.name}${key.slice(1)}`));
+}
 function boundaryViolation(root, edge, fromWorkspace, toWorkspace, ruleId, message) {
     return {
         ruleId,
@@ -413,7 +433,7 @@ function typeScriptContext(config, loaded, paths) {
         canonical, compilerError, isInside, slash, readTypeScriptProject, typeScriptProjectReferencePath,
         sameOrUnder, createTypeScriptProgram, isProductionSource, sourceLocation, workspaceMetadata, workspaceOf,
         pathAliasMatches, moduleReferences, workspaceSourceEntry, resolveTypeScriptModule, crossesSide, assetExtension: ASSET_EXTENSION,
-        relativePath, packageExported, boundaryViolation,
+        relativePath, packageExported, boundaryViolation, rootPackageOf, rootPackageEntryDeclared, rootPackageEntries,
     });
 }
 export function relativePath(root, fileName) {

package/runtime/scripts/hfs/explicit-surface-rule.mjs

@@ -6,7 +6,7 @@ const HINTS = {
     'parameter type': 'Give the parameter a type: `(value: Input)`.',
     'property type': 'Give the property a type: `name: Result = ...`.',
     'accessor type': 'Give the accessor a type: `get name(): Result` (a setter takes it from its parameter).',
-    'destructured export': 'A destructuring pattern cannot carry a type per name: export each name as its own variable with a type, `export const name: Type = source.name`.',
+    'destructured export': 'A destructuring pattern cannot carry a type per name: export each name as its own variable with a type, `export const name: Type = source.name`; a module definition is `export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<XOptions>()` (or `defineConfigurableModule`) of @starci/nest-kit, which states the types (`starci app codemod module-definition` writes it).',
     'exported value': 'Declare the type (an interface or a type alias) and annotate the export with it: `export const name: Shape = ...`.',
 };
 /** The `--isolatedDeclarations` flag name TypeScript ends its reasons with says nothing to the reader. */

package/runtime/scripts/hfs/manifest-shape.d.mts

@@ -64,6 +64,7 @@ export interface Slot {
     role?: string;
     importedBy?: string[];
     rewrittenBy?: string;
+    managedOnly?: boolean;
     logic?: string[];
     generatedBy?: string;
 }

package/runtime/scripts/hfs/manifest-shape.mjs

@@ -121,7 +121,7 @@ export const MANIFEST_KINDS = [APP_KIND, RUNTIME_KIND];
 /** The kind of a parsed manifest: `kind`, or app when absent (knowledge/hfs/slots.yaml carries none). */
 export const manifestKind = (m) => (isPlainObject(m) && m.kind !== undefined ? m.kind : APP_KIND);
 const strList = (v) => stringList(v);
-const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'role', 'importedBy', 'rewrittenBy', 'logic'];
+const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'role', 'importedBy', 'rewrittenBy', 'logic', 'managedOnly'];
 /** The roles a file slot may play that a rule reads (`role`): the entity registry of persistence.md BE-PERSISTENCE-3 (architecture/entity-registry.mjs). */
 const SLOT_ROLES = ['entity-registry'];
 /** The fields a slot's `lite` overlay may hold: the same keys it would carry in the slot body, resolved under edition lite. */
@@ -235,6 +235,8 @@ function slotListProblems(slot, at) {
         bad.push(`${at}: composedBy must be a non-empty list of unique app kinds`);
     if (slot.budget !== undefined && !budgetValid(slot.budget))
         bad.push(`${at}: budget must map names to positive integers`);
+    if (slot.managedOnly !== undefined && (slot.managedOnly !== true || slot.managedBy === undefined))
+        bad.push(`${at}: managedOnly is true and needs managedBy: the slot only lists files sync renders, and the slot owning the path judges them`);
     for (const key of ['managedBy', 'liteManagedBy'])
         if (slot[key] !== undefined && !NAME.test(String(slot[key])))
             bad.push(`${at}: ${key} must be a template id`);

package/runtime/scripts/hfs/rules/a15-findings.mjs

@@ -33,6 +33,8 @@ import { stacksIngressFindings } from './stacks-ingress.mjs';
 import { stacksLiteBackingFindings } from './stacks-lite-backing.mjs';
 import { stackToolingFindings } from './stack-tooling.mjs';
 import { stacksDeployFindings } from './stacks-deploy.mjs';
+import { stacksLocalFindings } from './stacks-local.mjs';
+import { stacksServiceImageFindings } from './stacks-service-images.mjs';
 import { stacksAuthCookieDomainFindings } from './stacks-auth-cookie-domain.mjs';
 import { ciCustodyFindings } from './ci-custody.mjs';
 import { workflowContextsFindings } from './workflow-contexts.mjs';
@@ -49,6 +51,7 @@ export const A15_CODES = [
     'HFS_WORKFLOW_CONTEXT',
     'CI_STANDARD',
     'CI_SECRET_SEALED', 'APP_SECRET_IN_CI', 'CI_DECLARATION_DRIFT',
+    'STACKS_LOCAL_CONFIG_INVALID', 'STACKS_DEV_UNDECLARED', 'STACKS_RUNBOOK_DOCKER_COMMAND',
     'BACKUP_PROOF_MISSING', 'BACKUP_UNDECLARED', 'BE_APP_BOOT_PROOF_MISSING', 'BOOT_PROOF_TIMEOUT', 'BE_APP_ENV_REQUIRED', 'BE_APP_MODULE_LIST_INLINE', 'BE_LITE_PROOF_LANE_MISSING', 'DB_ARCHIVE_MUTATED', 'DB_BASELINE_SHAPE', 'DB_EXTENSION_ALLOWED', 'DB_MIGRATION_DESTRUCTIVE', 'DB_PGMQ_DECLARED', 'DB_VAULT_WRITE', 'ENV_DUPLICATE', 'ENV_EXAMPLE_DRIFT', 'ENV_PUBLIC_SEALED', 'ENV_REQUIRED_UNSET', 'ENV_SEALED_UNREAD', 'ENV_VALUE_SHAPE', 'FE_STACK_CORE_MISSING', 'FE_STACK_UNLISTED', 'HFS_AGE_KEY_CUSTODY', 'HFS_APP_LEXICON', 'HFS_APP_WORKFLOW_TRIGGER', 'HFS_ASSET_KIND', 'HFS_ASSET_OVERSIZE', 'HFS_AUDIT_STEP_MISSING', 'HFS_AUTH_COOKIE_DOMAIN_MISSING', 'HFS_CANON_COPY_DRIFT', 'HFS_CI_TOOL_INSTALL', 'HFS_COVERAGE_BELOW', 'HFS_DB_DEPLOY_UNGUARDED', 'HFS_DEPENDABOT_MISSING', 'HFS_DEPLOY_COMPOSE_ON_VPS', 'HFS_DEPLOY_NO_LOGIC', 'HFS_DEPLOY_SCHEDULER', 'HFS_DEPLOY_WORKFLOW', 'HFS_DOC_COMMAND_UNKNOWN', 'HFS_DOC_ENV_UNKNOWN', 'HFS_DOC_PATH_MISSING', 'HFS_DOC_RULE_UNKNOWN', 'HFS_FEATURE_FILE_BUDGET', 'HFS_HOST_CRON', 'HFS_RELEASE_TAG_MISMATCH', 'HFS_SBOM_MISSING', 'HFS_SCHEDULE_UNDECLARED', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'HFS_SCRIPT_XTRACE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SEED_PII', 'HFS_UNUSED_SYMBOL', 'HFS_WORKFLOW_PIN', 'STACKS_DEPLOY_CONFIG_INVALID', 'STACKS_DNS_UNDECLARED', 'STACKS_HEALTHCHECK_MISSING', 'STACKS_HOST_UNROUTED', 'STACKS_INGRESS_UNDECLARED', 'STACKS_INGRESS_UNKNOWN', 'STACKS_LITE_REDIS_PERSISTENCE', 'STACKS_LITE_SELFHOSTED_DB', 'STACKS_MODEL_UNAVAILABLE', 'STACKS_PLACEMENT_MISSING', 'STACKS_PORT_PUBLISHED', 'STACKS_REALTIME_SCALED', 'STACKS_RELEASE_UNDECLARED', 'STACKS_SECOND_INGRESS', 'STACKS_SECRET_ENV_LITERAL', 'STACKS_SECRET_NOT_EXTERNAL', 'STACKS_SECRET_UNVERSIONED', 'STACKS_SIDECAR_DB_UNSUPPORTED', 'STACKS_SIDECAR_VOLUME_UNDECLARED', 'STACKS_TLS_UNDECLARED', 'STACKS_UPDATE_POLICY_MISSING', 'STACK_TOOLING_REIMPLEMENTED',
     // codes-end
 ];
@@ -87,6 +90,8 @@ export const FINDERS = [
     stacksLiteBackingFindings,
     stackToolingFindings,
     stacksDeployFindings,
+    stacksLocalFindings,
+    stacksServiceImageFindings,
     stacksAuthCookieDomainFindings,
     ciCustodyFindings,
     // finders-end

package/runtime/scripts/hfs/rules/database-access.mjs

@@ -1,4 +1,4 @@
-// R255-R256 inspect the final database access state: the application role, forced RLS, policies, views and storage prefixes.
+// R255-R256 inspect the final database access state: the application role (its attributes and every grant on schema auth), forced RLS, policies, views and storage prefixes.
 import { found } from './read.mjs';
 import { parseSql } from '../sql/pg-parse.mjs';
 import { eachInOrder } from '../../lib/in-order.mjs';
@@ -20,6 +20,10 @@ const AND = ['AND', 'EXPR'].join('_');
 const OR = ['OR', 'EXPR'].join('_');
 const NOT = ['NOT', 'EXPR'].join('_');
 const SEQUENCE = ['OBJECT', 'SEQUENCE'].join('_');
+const SCHEMA = ['OBJECT', 'SCHEMA'].join('_');
+const TABLE = ['OBJECT', 'TABLE'].join('_');
+const ALL_IN_SCHEMA = ['ACL', 'TARGET', 'ALL', 'IN', 'SCHEMA'].join('_');
+const ACCOUNT_SCHEMA = 'auth';
 const MATVIEW = ['OBJECT', 'MATVIEW'].join('_');
 const note = (code, source, message, extra = {}) => found(code, source.file, `${source.file}:${source.line} ${message}`, { line: source.line, ...extra });
 function someNode(node, predicate) {
@@ -157,6 +161,39 @@ function roleFindings(analyses, appRole) {
     }
     return findings;
 }
+/** What one grant statement names inside schema auth: the schema, a table or sequence of it, every table or sequence in it. */
+function authTargets(grant) {
+    if (grant.objtype === SCHEMA)
+        return grant.objects.filter((object) => sval(object) === ACCOUNT_SCHEMA).map(() => `schema ${ACCOUNT_SCHEMA}`);
+    if (![TABLE, SEQUENCE].includes(grant.objtype))
+        return [];
+    if (grant.targtype === ALL_IN_SCHEMA)
+        return grant.objects.filter((object) => sval(object) === ACCOUNT_SCHEMA).map(() => `all ${grant.objtype === TABLE ? 'tables' : 'sequences'} in schema ${ACCOUNT_SCHEMA}`);
+    return grant.objects.filter((object) => object.RangeVar?.schemaname === ACCOUNT_SCHEMA).map((object) => relationName(object.RangeVar));
+}
+/**
+ * R255: the application role holds no privilege on schema auth, on a table or sequence in it, or by default privilege for the
+ * schema. The migrations are applied in order, so a grant that a later migration revokes (the contract step of an app that moved
+ * to the identity account doors) is not held; what remains at the end is reported at the grant that left it.
+ */
+function authSchemaFindings(analyses, appRole) {
+    const held = new Map();
+    for (const { file, facts } of analyses) {
+        const statements = [
+            ...facts.grants.map((grant) => ({ grant, targets: authTargets(grant) })),
+            ...facts.defaultPrivileges.map((grant) => ({ grant, targets: grant.schemas.includes(ACCOUNT_SCHEMA) ? [`default privileges in schema ${ACCOUNT_SCHEMA}`] : [] })),
+        ].filter(({ grant }) => grant.grantees.includes(appRole));
+        for (const { grant, targets } of statements) {
+            for (const target of targets) {
+                const state = held.get(target) ?? { target, privileges: new Set() };
+                updatePrivileges(state, grant.grant, grant.all ? ['all'] : grant.privileges);
+                held.set(target, { ...state, file, line: grant.line });
+            }
+        }
+    }
+    return [...held.values()].filter((state) => state.privileges.size > 0)
+        .map((state) => note(DB_APP_ROLE, state, `${appRole} holds a grant on ${state.target}; reach accounts through the identity account doors (SECURITY DEFINER functions), never through a grant on schema ${ACCOUNT_SCHEMA}; an app on the old sign-in glue runs "starci app codemod account-doors", "starci app sync --execute" and "starci app codemod account-doors --contract" in one release`, { target: state.target }));
+}
 function roleStatementFindings(statement, appRole) {
     const { type, node } = statement;
     if (!['CreateRoleStmt', 'AlterRoleStmt'].includes(type))
@@ -299,6 +336,7 @@ export async function databaseAccessFindings({ analyses, exposed, db = {} }) {
     return [
         ...policyFindings(policies, appRole, helpers),
         ...roleFindings(analyses, appRole),
+        ...authSchemaFindings(analyses, appRole),
         ...forceFindings(analyses, declared, appRole),
         ...viewFindings(analyses, grants, exposed),
         ...storagePrefixFindings(policies, helpers),

package/runtime/scripts/hfs/rules/monorepo.d.mts

@@ -1,6 +1,10 @@
 import type { Parsed, Repo } from './rule-types.mjs';
 /** The npm workspaces of every app, in this order. */
 export declare const WORKSPACES: readonly string[];
+/** The workspace of the app's own root packages (slot app.packages: packages/agent-sdk, packages/module-<name>), added after the fe ones once one is tracked. */
+export declare const ROOT_PACKAGES_WORKSPACE = "packages/*";
+/** The workspaces the tracked tree `files` calls for: the fe ones, then `packages/*` when a root package tracks its package.json. */
+export declare const workspacesFor: (files: readonly string[]) => readonly string[];
 /** The scripts of every fe app workspace, exactly: turbo runs build, dev and typecheck; start serves a build. The lint is the root's (`starci app check --gate lint`), never a workspace script. */
 export declare const FE_APP_SCRIPTS: Readonly<Record<string, string>>;
 /** The package manager every app root declares (turbo reads it to parse the lockfile); the starci app scaffold writes it. */