@starci/hfs 5.0.8 → 5.2.0

package/runtime/knowledge/hfs/slots.yaml

@@ -7,7 +7,7 @@
 # catalog READ this file through scripts/hfs/slots.mjs; none of them hardcodes a path.
 # Shape: modules/schemas/hfs-slots.schema.yaml. The repository side is hfs.json: modules/schemas/hfs-repo.schema.yaml.
 schema: starci/hfs-slots@3
-version: 3.15.0
+version: 3.16.0
 
 versioning:
   # MAJOR.MINOR.PATCH of this manifest. A repository pins only the MAJOR in hfs.json ("hfs": 3).
@@ -117,6 +117,8 @@ versioning:
 #               liteManagedBy is managed only in lite; its effective lite.path still lists literal files.
 #               the managed file list lives here and nowhere in code. A difference is HFS_MANAGED_FILE_DRIFT (a
 #               back end's tsconfig.json: HFS_TS_STRICT when a flag or an option was added).
+#   managedOnly true: the slot only lists files sync renders (needs managedBy); the path is judged by the slot that owns it, so the rendered
+#               file keeps the rules and the tier of its folder (a sign-in service is a domain service)
 #   rules       rule codes from knowledge/hfs/rules.yaml.
 #   editions    the editions (below) the slot exists in; default all of them. A slot outside the declared edition owns
 #               no path - under lite, what full keeps absent is removed, and what lite forbids is a finding.
@@ -250,17 +252,20 @@ ruleParams:
       "node:https": [platform/http]
       http: [platform/http]
       https: [platform/http]
-      "@aws-sdk/client-s3": [integrations/object-storage]       # the ObjectStorage port: one S3 adapter for MinIO, S3 and Spaces (R331)
-      "@aws-sdk/s3-request-presigner": [integrations/object-storage]
-      minio: []                                          # storage goes through the S3 client of integrations/object-storage
+      "@aws-sdk/client-s3": []                           # the S3 client is a dependency of @starci/object-storage, imported by no app file (R331)
+      "@aws-sdk/s3-request-presigner": []
+      "@starci/object-storage": [integrations/object-storage]   # the ObjectStorage port: one S3 adapter for MinIO, S3 and Spaces (R331)
+      minio: []                                          # storage goes through @starci/object-storage
       "@supabase": []                                    # no Supabase client in a back end
-      "@nestjs/passport": [integrations/passport]        # the identity libraries (R328)
-      passport: [integrations/passport]
-      passport-google-oauth20: [integrations/passport]
-      passport-local: [integrations/passport]
-      "@nestjs/jwt": [integrations/passport]
-      jose: [integrations/passport]
-      bcryptjs: [integrations/passport]
+      "@nestjs/passport": []                             # the identity libraries are @starci/auth's dependencies, never an app's (R328)
+      passport: []
+      passport-google-oauth20: []
+      passport-local: []
+      "@nestjs/jwt": []
+      jose: []
+      bcryptjs: []
+      "@starci/auth": [integrations/passport]            # the lite sign-in package: its server entry is reached only through integrations/passport (R328)
+      "@starci/auth/testing": [integrations/passport]   # its test doubles, for the glue's specs
       bcrypt: []
       cache-manager: [integrations/cache, integrations/redis]
       "@nestjs/cache-manager": [integrations/cache, integrations/redis]     # the CACHE_MANAGER token: caching goes through the cache capability
@@ -909,7 +914,7 @@ slots:
     # The db service supplies the database; schedules are platform/jobs ticks (R335); production has no Compose or host cron.
     lite:
       requires: [application-stacks.yaml]
-      allows: [application-stacks.yaml, images/db/Dockerfile, "<env>/README.md", "<env>/environment.json", "<env>/infra/swarm/**", "<env>/infra/metadata.json",
+      allows: [application-stacks.yaml, images/db/Dockerfile, "<env>/README.md", "<env>/environment.json", "<env>/infra/{compose,swarm}/**", "<env>/infra/metadata.json",
                "<env>/runtime/{config,env}/**", "<env>/runtime/env/KEYS.md", "<env>/secrets/<slug>.{enc.yaml,enc}", "<env>/secrets/.gitkeep", "<env>/seeds/**"]
       forbids: ["<env>/runtime/files/**", "**/*.enc outside <env>/secrets/", DESIGN.md, deployment.json, "k8s/ at root"]
     rules: [HFS_STACKS_SHAPE, HFS_STACKS_IN_SIDE, HFS_PLAINTEXT_SECRET, HFS_IDENTITY_CUSTODY]
@@ -2028,36 +2033,68 @@ slots:
     editions: [lite]
     exemplifiedBy:
       - packages/hfs/templates/be/skeleton-lite/src/modules/integrations/passport/
-    # The one owner of the lite identity libraries (ruleParams.be.infraOwners: @nestjs/passport, passport, passport-google-oauth20,
-    # passport-local, @nestjs/jwt, jose, bcryptjs): the Google OAuth 2.0 strategy (state and PKCE), the local email and password
-    # strategy (bcrypt), the app's own asymmetric access tokens and their JWKS, and the rotating refresh cookie. domain/identity
-    # verifies a token through this integration's verifier and builds the principal (contexts/code/be/api-auth.md).
+    # The glue of @starci/auth, the lite sign-in package (Google OAuth with state and PKCE, email and password, EdDSA access tokens with
+    # their JWKS, rotating refresh sessions): the one importer of the package (ruleParams.be.infraOwners), which owns the identity
+    # libraries (@nestjs/passport, passport, passport-google-oauth20, passport-local, @nestjs/jwt, jose, bcryptjs) that no app imports.
+    # It parses the typed options, builds the verifier and names the injectors; domain/identity verifies a token through the kit and
+    # builds the principal (contexts/code/be/api-auth.md).
     path: "src/modules/integrations/passport/"
     presence: required
     tracked: tracked
     tier: integrations
     owner: true
-    requires: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.tokens.ts, passport.password.ts, passport.cookie.ts]   # Secrets, no defaults (R44); options and named injectors (R83); tokens and JWKS; bcrypt; the refresh cookie
-    allows: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.tokens.ts, passport.password.ts, passport.cookie.ts, strategies/, errors/]
-    logic: [passport.tokens.ts, passport.password.ts, passport.cookie.ts]   # JWT sign and verify over the own JWKS, bcrypt, the refresh cookie: measured at 100 per file
+    requires: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.kit.ts, passport.registration.ts]   # Secrets, no defaults (R44); options and named injectors (R83); the kit and the module over @starci/auth
+    allows: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.kit.ts, passport.registration.ts, errors/]
+    logic: [passport.kit.ts]   # the verifier mapping over the package: measured at 100 per file
     tests: unit-beside
     rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER, BE_AUTH_PASSPORT_OWNER, BE_AUTH_JWT_OWN_JWKS, BE_AUTH_REFRESH_COOKIE]
     coverage: required
     since: 3.9.0
+  - id: be.identity.sign-in
+    since: 3.16.0
+    profiles: [be]
+    editions: [lite]
+    editionWhy: "lite signs people in with the package @starci/auth, so its sign-in glue is rendered, not written (owner ruling auth-package); full uses its identity provider."
+    # The identity capability's sign-in glue over @starci/auth: the entities of the session, attempt and user tables, the stores the package asks for (sessions, accounts, rate counter), the authenticator and the service the doors call, with their specs. `starci app sync` renders them; a hand edit is drift.
+    path: "{src/modules/domain/identity/account-directory.service.spec.ts,src/modules/domain/identity/account-directory.service.ts,src/modules/domain/identity/authenticator.service.spec.ts,src/modules/domain/identity/authenticator.service.ts,src/modules/domain/identity/persistence/entities/auth-identity.entity.ts,src/modules/domain/identity/persistence/entities/auth-user.entity.ts,src/modules/domain/identity/persistence/entities/identity-attempt.entity.ts,src/modules/domain/identity/persistence/entities/identity-refresh-token.entity.ts,src/modules/domain/identity/persistence/entities/identity-session.entity.ts,src/modules/domain/identity/persistence/entities/index.ts,src/modules/domain/identity/rate-counter.service.spec.ts,src/modules/domain/identity/rate-counter.service.ts,src/modules/domain/identity/session-store.service.spec.ts,src/modules/domain/identity/session-store.service.ts,src/modules/domain/identity/sign-in.service.spec.ts,src/modules/domain/identity/sign-in.service.ts,src/tests/fixtures/builders/identity.builder.ts}"
+    presence: optional
+    tracked: tracked
+    tier: inherit
+    tests: unit-beside
+    coverage: none
+    managedBy: auth-lite
+    managedOnly: true     # lists files sync renders; the slot owning the path judges them
+    rules: [HFS_MANAGED_FILE_DRIFT]
+  - id: be.feature.auth
+    since: 3.16.0
+    profiles: [be]
+    editions: [lite]
+    editionWhy: "lite signs people in with the package @starci/auth, so its sign-in glue is rendered, not written (owner ruling auth-package); full uses its identity provider."
+    # The auth feature: the REST doors under /auth (login, refresh, session, logout, Google start and callback, jwks) over IdentitySignInService, one command or query and handler per door.
+    path: "{src/features/api/auth/application/auth.contracts.ts,src/features/api/auth/application/get-jwks.handler.ts,src/features/api/auth/application/get-jwks.query.ts,src/features/api/auth/application/google-begin.command.ts,src/features/api/auth/application/google-begin.handler.ts,src/features/api/auth/application/google-complete.command.ts,src/features/api/auth/application/google-complete.handler.ts,src/features/api/auth/application/login.command.ts,src/features/api/auth/application/login.handler.ts,src/features/api/auth/application/logout.command.ts,src/features/api/auth/application/logout.handler.ts,src/features/api/auth/application/refresh.command.ts,src/features/api/auth/application/refresh.handler.ts,src/features/api/auth/application/session.command.ts,src/features/api/auth/application/session.handler.ts,src/features/api/auth/auth.module-definition.ts,src/features/api/auth/auth.module.ts,src/features/api/auth/auth.options.ts,src/features/api/auth/index.ts,src/features/api/auth/transport/http/auth-http.module-definition.ts,src/features/api/auth/transport/http/auth-http.module.ts,src/features/api/auth/transport/http/auth-http.options.ts,src/features/api/auth/transport/http/auth.controller.ts,src/features/api/auth/transport/http/dto/google-start.request.ts,src/features/api/auth/transport/http/dto/login.request.ts}"
+    presence: optional
+    tracked: tracked
+    tier: inherit
+    tests: none
+    coverage: none
+    managedBy: auth-lite
+    managedOnly: true     # lists files sync renders; the slot owning the path judges them
+    rules: [HFS_MANAGED_FILE_DRIFT]
   - id: be.integrations.object-storage
     profiles: [be]
     exemplifiedBy:
       - packages/hfs/templates/be/skeleton-lite/src/modules/integrations/object-storage/
-    # The one owner of the S3 client (@aws-sdk/client-s3 and @aws-sdk/s3-request-presigner) over S3-compatible storage (MinIO in
-    # lite): the ObjectStorage port with presigned PUT and GET; no other module imports an S3 SDK or minio.
+    # The glue of @starci/object-storage, the owner of the S3 client (@aws-sdk/client-s3 and @aws-sdk/s3-request-presigner) over
+    # S3-compatible storage (MinIO in lite): this folder keeps the bucket, parses the settings and registers the module; no app
+    # file imports an S3 SDK or minio, and no other module imports the package.
     path: "src/modules/integrations/object-storage/"
     presence: optional
     litePresence: required
     tracked: tracked
     tier: integrations
     owner: true
-    requires: [index.ts, object-storage.config.ts, object-storage.options.ts, object-storage.decorators.ts, object-storage.client.ts]
-    allows: [index.ts, object-storage.module.ts, object-storage.module-definition.ts, object-storage.config.ts, object-storage.options.ts, object-storage.decorators.ts, object-storage.client.ts, errors/]
+    requires: [index.ts, object-storage.config.ts, object-storage.options.ts, object-storage.decorators.ts, object-storage.module-definition.ts, object-storage.module.ts]
+    allows: [index.ts, object-storage.config.ts, object-storage.options.ts, object-storage.decorators.ts, object-storage.module-definition.ts, object-storage.module.ts, errors/]
     tests: unit-beside
     rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER, BE_STORAGE_OWNER]
     coverage: required
@@ -2591,7 +2628,7 @@ slots:
     profiles: [fe]
     # The identity-provider client (fe-stack auth, FE-AUTH): the session, the access token the Apollo link attaches and the
     # sign-in/sign-out calls. It talks only to the app's own back-end auth doors and holds no credential: the refresh token lives in
-    # the back end's httpOnly cookie and the access token in memory (ruling:lite-self-hosted-postgres-passport-minio).
+    # the back end's httpOnly cookie and the access token in the memory of the one @starci/auth client (ruling:lite-self-hosted-postgres-passport-minio).
     path: "apps/<app>/src/modules/auth/"
     presence: optional
     tracked: tracked
@@ -2601,6 +2638,20 @@ slots:
     tests: none
     since: 3.0.0
     rules: [FE_STACK_FORBIDDEN]
+  - id: fe.modules.auth.client
+    since: 3.16.0
+    profiles: [fe]
+    editions: [lite]
+    editionWhy: "lite signs people in with the package @starci/auth, so its auth client is rendered, not written (owner ruling auth-package); full wires its identity provider."
+    # The AuthClient every edition shares, implemented by one @starci/auth/client instance over the app's own back-end auth doors.
+    path: "apps/web/src/modules/auth/client.ts"
+    presence: optional
+    tracked: tracked
+    tier: inherit
+    tests: none
+    managedBy: auth-lite
+    managedOnly: true     # lists files sync renders; the slot owning the path judges them
+    rules: [HFS_MANAGED_FILE_DRIFT]
   - id: fe.modules.toast
     profiles: [fe]
     # Mutation feedback (fe-stack toast, FE-TOAST): the HeroUI toast wrapper, showGraphQLToast over a GraphQLResponse and the

package/runtime/modules/kernel/failure-codes.yaml

@@ -5347,6 +5347,36 @@ SEALED_FILE_IN_WORK:
 
 # --- HFS rule catalog (knowledge/hfs/rules.yaml): one code per rule, from R01 up ---
 
+STACKS_LOCAL_CONFIG_INVALID:
+  title: "The local block of a docker-compose environment is not coherent"
+  title_vi: "Khối local của môi trường docker-compose không nhất quán"
+  meaning_vi: "environments.<env>.local thiếu hoặc có trường lạ, cổng trùng, dịch vụ không có trong tệp compose, vai trò cơ sở dữ liệu dùng chung, hoặc thăm dò không nằm trên loopback."
+  causes_vi:
+    - "Vi phạm R372: khối local được kiểm bằng đúng normalizeLocal mà các động từ starci app stack up, down, doctor dùng."
+  nextStep_vi: "Sửa đúng trường nêu trong thông báo (environments.<env>.local.<đường dẫn>), rồi chạy lại starci app check."
+  owner: op-retry
+  kind: check-finding
+
+STACKS_DEV_UNDECLARED:
+  title: "A lite app declares no runnable dev environment"
+  title_vi: "Ứng dụng lite chưa khai báo môi trường dev chạy được"
+  meaning_vi: "Không có environment nào có runtime docker-compose và khối local, nên starci app stack up --env dev không có gì để chạy."
+  causes_vi:
+    - "Vi phạm R372: môi trường dev vẫn là Swarm hoặc chưa được khai báo."
+  nextStep_vi: "Khai báo environments.dev với runtime docker-compose, composeFiles và khối local; runbook của nó nêu starci app stack up --env dev."
+  owner: op-retry
+  kind: check-finding
+
+STACKS_RUNBOOK_DOCKER_COMMAND:
+  title: "A dev runbook carries a docker command or omits the one-command start"
+  title_vi: "Runbook dev chứa lệnh docker hoặc không nêu lệnh khởi động duy nhất"
+  meaning_vi: "README của môi trường docker-compose có dòng docker build, run, compose hay stack deploy, hoặc không nêu starci app stack up --env <env>."
+  causes_vi:
+    - "Vi phạm R373 và quy tắc cứng 8: Docker do harness chạy, tác tử không chạy tay."
+  nextStep_vi: "Thay các lệnh docker bằng starci app stack up --env <env> --execute và các động từ down, status, logs của nó."
+  owner: op-retry
+  kind: check-finding
+
 STACKS_DEPLOY_CONFIG_INVALID:
   title: "A deploy block of application-stacks.yaml is not coherent"
   title_vi: "Khối deploy trong application-stacks.yaml không nhất quán"
@@ -5674,3 +5704,35 @@ BE_JOBS_SCHEDULER_OWNER:
   nextStep_vi: "Khai tick vào JOB_TICKS của platform/jobs/job-ticks.contracts.ts (name, cron, timeZone UTC, queue, payload) và xoá lịch tự viết; giữ advisoryXactLock và job_tick_claim trong JobTickService."
   owner: op-retry
   kind: check-finding
+
+STACKS_CODE_BIND_MOUNT:
+  title: "A stack or compose file bind-mounts code into a service container"
+  title_vi: "Tệp stack hoặc compose gắn (bind-mount) mã vào container của dịch vụ"
+  meaning_vi: "Một dịch vụ gắn thư mục hoặc tệp mã, plugin, script hay đường dẫn ghi được của repository từ máy chủ vào container."
+  causes_vi:
+    - "Vi phạm R374: mã của dịch vụ phải nằm trong image dựng từ .starcistacks/images/<tên>/, không gắn lúc chạy."
+  nextStep_vi: "Đưa mã vào Dockerfile của .starcistacks/images/<tên>/ (FROM image đã ghim digest, hoặc image fork của harness) và bỏ bind-mount; chỉ giữ volume dữ liệu, secret và tệp cấu hình thuần dữ liệu chỉ đọc."
+
+STACKS_IMAGE_BASE_UNPINNED:
+  title: "A service image folder has a FROM that is not digest-pinned"
+  title_vi: "Thư mục image của dịch vụ có FROM chưa ghim digest"
+  meaning_vi: "Dockerfile trong .starcistacks/images/<tên>/ dùng FROM theo tag, không theo name@sha256:..."
+  causes_vi:
+    - "Vi phạm R374: mọi image nền phải ghim digest."
+  nextStep_vi: "Ghim FROM bằng name@sha256:<digest>."
+
+STACKS_IMAGE_BASE_NOT_FORK:
+  title: "A service image folder does not build on the harness fork image"
+  title_vi: "Thư mục image của dịch vụ không dựng trên image fork của harness"
+  meaning_vi: "Harness sở hữu image fork StarCi cho dịch vụ này (images/sources.json) nhưng giai đoạn cuối của Dockerfile không FROM image đó."
+  causes_vi:
+    - "Vi phạm R374: dịch vụ tùy biến phải dựng trên image fork do harness ghim."
+  nextStep_vi: "Đặt FROM <repository fork>@sha256:<digest> ở giai đoạn cuối."
+
+STACKS_IMAGE_ENV_DIVERGES:
+  title: "A service with an image folder runs a third-party image in an environment"
+  title_vi: "Dịch vụ có thư mục image chạy image bên thứ ba ở một môi trường"
+  meaning_vi: "Dev và production phải cùng chạy một image dựng từ .starcistacks/images/<tên>/."
+  causes_vi:
+    - "Vi phạm R374: một môi trường dùng image upstream hoặc image nước ngoài thay vì image dựng từ thư mục."
+  nextStep_vi: "Dùng build.context trỏ tới thư mục image (compose) hoặc tham chiếu image của dự án (stack)."

package/runtime/modules/schemas/application-stacks.schema.yaml

@@ -510,6 +510,12 @@ $defs:
       runbook: {type: string, minLength: 1}
       secrets: {type: array, items: {$ref: '#/$defs/secret'}}
       deploy: {$ref: '#/$defs/deploy'}
+      local:
+        description: >-
+          The dev declaration `starci app stack up|down|doctor|prepare|status|logs|verify` runs for a docker-compose environment (PROJECT-STACKS-6):
+          ports, compose services, the environment's own database role, dev-only custody to generate once, setup and seed commands, native app
+          processes, readiness and verification probes. Names, ports and argv lists only, never a value. The authority is scripts/hfs/stack-local-config.mjs; rule R340 judges it.
+        type: object
       ingress:
         description: "The one selected ingress component and the hosts it routes, or external with the stack name when the ingress is a shared stack outside this one (then no component; rule R275 judges which of the two is declared)."
         type: object

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/test-world-files.d.mts

@@ -18,9 +18,10 @@ interface WorldViolation {
  *    its own slot, be.tests.world.kit) plus files at its root whose role suffix is in ruleParams.be.suffixes
  *    (`stripe.client.ts`, `checkout.contracts.ts`, `test-world.config.ts`, ...). Every tracked file below the world root is
  *    matched by the slot's own entries through `allowsFile`.
- * 2. The declaration. `test-world.config.ts` declares the world in ONE form, the named export R89 allows:
- *    `export const { useTestWorld, useSandbox } = defineTestWorld({ ... })` (an exported `const` initialized by a
- *    `defineTestWorld(<object literal>)` call). A config without it (a default export, or a declaration the machine cannot
+ * 2. The declaration. `test-world.config.ts` declares the world in a named form R89 allows: the destructured export
+ *    `export const { useTestWorld, useSandbox } = defineTestWorld({ ... })`, or the typed form
+ *    `const world: TestWorldApi = defineTestWorld({ ... })` whose `useTestWorld` and `useSandbox` are exported consts typed from
+ *    `TestWorldApi` (a `const` initialized by a `defineTestWorld(<object literal>)` call). A config without it (a default export, or a declaration the machine cannot
  *    read) is refused: the world it declares could not be judged.
  * 3. Fakes against the stack (owner refinement 2026-09-30). Every service the stack declares runs real in the world; a fake
  *    (a `fakes/<provider>/` folder, or a `fakes` entry of the declaration such as `smtp: smtpFake()`) is a network-edge fake

package/runtime/scripts/hfs/architecture/test-world-files.mjs

@@ -15,9 +15,10 @@ import { byCodeUnit } from '../../lib/list.mjs';
  *    its own slot, be.tests.world.kit) plus files at its root whose role suffix is in ruleParams.be.suffixes
  *    (`stripe.client.ts`, `checkout.contracts.ts`, `test-world.config.ts`, ...). Every tracked file below the world root is
  *    matched by the slot's own entries through `allowsFile`.
- * 2. The declaration. `test-world.config.ts` declares the world in ONE form, the named export R89 allows:
- *    `export const { useTestWorld, useSandbox } = defineTestWorld({ ... })` (an exported `const` initialized by a
- *    `defineTestWorld(<object literal>)` call). A config without it (a default export, or a declaration the machine cannot
+ * 2. The declaration. `test-world.config.ts` declares the world in a named form R89 allows: the destructured export
+ *    `export const { useTestWorld, useSandbox } = defineTestWorld({ ... })`, or the typed form
+ *    `const world: TestWorldApi = defineTestWorld({ ... })` whose `useTestWorld` and `useSandbox` are exported consts typed from
+ *    `TestWorldApi` (a `const` initialized by a `defineTestWorld(<object literal>)` call). A config without it (a default export, or a declaration the machine cannot
  *    read) is refused: the world it declares could not be judged.
  * 3. Fakes against the stack (owner refinement 2026-09-30). Every service the stack declares runs real in the world; a fake
  *    (a `fakes/<provider>/` folder, or a `fakes` entry of the declaration such as `smtp: smtpFake()`) is a network-edge fake
@@ -38,6 +39,7 @@ const FAKES_DIRECTORY = 'fakes/';
 const CONFIG_FILE = 'test-world.config.ts';
 const DEFINE = 'defineTestWorld';
 const NAMED_FORM = `export const { useTestWorld, useSandbox } = ${DEFINE}({ ... })`;
+const TYPED_FORM = `const world: TestWorldApi = ${DEFINE}({ ... })` + ' with export const useTestWorld / useSandbox typed from it';
 const defaultEnvironment = DEFAULT_ENVIRONMENT;
 const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const unwrap = (ts, node) => unwrapEach(ts, node, [ts.isParenthesizedExpression, ts.isAsExpression, ts.isSatisfiesExpression]);
@@ -52,21 +54,38 @@ function defineLiteral(ts, expression) {
     const literal = first ? unwrap(ts, first) : null;
     return literal && ts.isObjectLiteralExpression(literal) ? literal : null;
 }
-/** The declaration of the world: the object literal of an exported `const` initialized by `defineTestWorld({ ... })`, or null. */
+/**
+ * The declaration of the world: the object literal of a top-level `const` initialized by `defineTestWorld({ ... })`, or null. The config
+ * exports `useTestWorld` and `useSandbox` either by destructuring that call (the original form) or, typed, from the world the call
+ * built: `const world: TestWorldApi = defineTestWorld({ ... })` with `export const useTestWorld: TestWorldApi["useTestWorld"] = world.useTestWorld`.
+ * Both are read; a world no exported name reaches is refused by the caller.
+ */
 function configLiteral(ts, sourceFile) {
     for (const statement of sourceFile.statements) {
-        if (!ts.isVariableStatement(statement) || !isExported(ts, statement))
+        if (!ts.isVariableStatement(statement))
             continue;
         if (!hasAnyFlag(statement.declarationList.flags, ts.NodeFlags.Const))
             continue;
         for (const declaration of statement.declarationList.declarations) {
             const literal = declaration.initializer ? defineLiteral(ts, declaration.initializer) : null;
-            if (literal)
+            if (literal && (isExported(ts, statement) || exportsWorld(ts, sourceFile)))
                 return literal;
         }
     }
     return null;
 }
+/** Whether the file exports both `useTestWorld` and `useSandbox` as consts (the typed form re-exports them from the built world). */
+function exportsWorld(ts, sourceFile) {
+    const exported = new Set();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement) || !isExported(ts, statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations)
+            if (ts.isIdentifier(declaration.name))
+                exported.add(declaration.name.text);
+    }
+    return exported.has('useTestWorld') && exported.has('useSandbox');
+}
 /** `stack` as the environment it names: the last segment of `".starcistacks/<env>"`; null when absent or not a literal. */
 function environmentOf(ts, literal) {
     const node = literal ? propertyOf(ts, literal, 'stack') : null;
@@ -152,7 +171,7 @@ function worldDeclaration(graph, ts, worldRoot, violations) {
     if (configFile && !literal) {
         violations.push({
             ruleId: RULE, path: configPath, line: 1, column: 1, slot: WORLD_SLOT,
-            message: `${configPath} declares no world the machine can read. Declare it in the one named form \`${NAMED_FORM}\` (an exported const of a ${DEFINE} call with an object literal, imported from @starci/test-world); a default export is refused by R89 and is not read.`,
+            message: `${configPath} declares no world the machine can read. Declare it in the named form \`${NAMED_FORM}\` or the typed form \`${TYPED_FORM}\` (a const of a ${DEFINE} call with an object literal, imported from @starci/test-world); a default export is refused by R89 and is not read.`,
         });
     }
     return { configPath, configFile, literal };

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/explicit-surface-rule.d.mts

@@ -0,0 +1,58 @@
+import type { TypeScript } from '../lib/ts-ast.mjs';
+/** The part of an ESLint rule context the rule reads (typescript-eslint's context satisfies it). */
+export interface SurfaceContext {
+    readonly filename: string;
+    readonly sourceCode: {
+        readonly text: string;
+        getLocFromIndex(index: number): {
+            line: number;
+            column: number;
+        };
+        readonly parserServices?: {
+            readonly program?: {
+                getCompilerOptions(): {
+                    module?: number;
+                };
+            } | null;
+        } | undefined;
+    };
+    report(descriptor: {
+        loc: {
+            start: {
+                line: number;
+                column: number;
+            };
+            end: {
+                line: number;
+                column: number;
+            };
+        };
+        messageId: string;
+        data: Record<string, string>;
+    }): void;
+}
+/** The rule module the factory returns: a plain ESLint rule with one message. */
+export interface SurfaceRule {
+    meta: {
+        type: 'problem';
+        docs: {
+            description: string;
+        };
+        schema: [];
+        messages: {
+            inferred: string;
+        };
+    };
+    create(context: SurfaceContext): {
+        Program(): void;
+    };
+}
+/**
+ * The rule. `ts` is the canon's own TypeScript (its peer dependency); the side's `module` option comes from the typed program when the file is linted with one.
+ *
+ * @param input - `ts` is the compiler.
+ * @returns An ESLint rule reporting each export of a TypeScript source whose type is inferred.
+ */
+export declare const explicitSurfaceRule: ({ ts }: {
+    ts: TypeScript;
+}) => SurfaceRule;