@north-light/api 0.3.440 → 0.3.441

package/dist/core/canvas/paths.d.ts

@@ -39,6 +39,8 @@ export declare function isolatedNodeHome(nodeId: string, grantee: string): strin
 /** The HOME a node's processes get: its own home in an isolated run, else the app's. */
 export declare function nodeHome(nodeId: string, grantee: string, isolated: boolean): string;
 export declare function nodeRunDir(nodeId: string): string;
+/** The run's scope allow-list as a JSON array, beside `broker-launch.json`. */
+export declare function scopesFilePath(nodeId: string): string;
 export declare function contextDir(nodeId: string, grantee?: string): string;
 /** Replace the literal env-var tokens `$CRTR_CONTEXT_DIR` / `$CRTR_NODE_ID` in
  *  agent-facing doc text with the node's real values, so a doc surfaced INTO a

package/dist/core/canvas/paths.js

@@ -96,6 +96,10 @@ export function nodeRunDir(nodeId) {
     assertSafeNodeId(nodeId);
     return process.platform === 'linux' ? join(socketDir(), 'nodes', nodeId) : join(nodeRecordDir(nodeId), 'run');
 }
+/** The run's scope allow-list as a JSON array, beside `broker-launch.json`. */
+export function scopesFilePath(nodeId) {
+    return join(nodeRunDir(nodeId), 'scopes.json');
+}
 export function contextDir(nodeId, grantee) {
     return join(nodeAgentDir(nodeId, grantee), 'context');
 }

package/dist/shared/env.d.ts

@@ -18,10 +18,17 @@ export declare function envGrantee(): string | undefined;
  *  that variable is not this signal. */
 export declare const INBOX_BETWEEN_TURNS_ENV = "CRTR_INBOX_BETWEEN_TURNS";
 export declare function envInboxBetweenTurns(): boolean;
+/** Path of the JSON file holding the run's scope allow-list (set by `nodeEnv`). */
+export declare const SCOPES_FILE_ENV = "CRTR_SCOPES_FILE";
 /** The current run's scope allow-list; null means the row inherits everything. */
 export declare function envScopes(): readonly string[] | null;
 /** Whether a launched scope list covers a capability. Null means not narrowed. */
 export declare function scopeAllowed(scopes: readonly string[] | null | undefined, scope: string): boolean;
+/** Whether any held scope covers `scope`. A held scope equal to the request always covers it, so the
+ *  common case of a run narrowed to a subset of its grant is a string scan instead of `covers` on every
+ *  pair (a 10,000-scope grant checked against 10,000 scopes is otherwise ~15 s). A request `covers`
+ *  would reject as unparseable still throws. */
+export declare function coveredByAny(held: readonly string[], scope: string): boolean;
 export declare function envExecutionId(): string | undefined;
 /** The current node's target profile id (`CRTR_PROFILE_ID`), or undefined. */
 export declare function envProfileId(): string | undefined;

package/dist/shared/env.js

@@ -75,8 +75,18 @@ export const INBOX_BETWEEN_TURNS_ENV = 'CRTR_INBOX_BETWEEN_TURNS';
 export function envInboxBetweenTurns() {
     return process.env[INBOX_BETWEEN_TURNS_ENV] === '1';
 }
+/** Path of the JSON file holding the run's scope allow-list (set by `nodeEnv`). */
+export const SCOPES_FILE_ENV = 'CRTR_SCOPES_FILE';
 /** The current run's scope allow-list; null means the row inherits everything. */
 export function envScopes() {
+    const file = process.env[SCOPES_FILE_ENV];
+    if (file !== undefined && file !== '') {
+        // A listed file that cannot be read must not widen the run: fail closed.
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        if (!Array.isArray(parsed) || parsed.some((scope) => typeof scope !== 'string'))
+            throw new Error(`invalid scopes file ${file}`);
+        return parsed;
+    }
     const raw = process.env['CRTR_SCOPES'];
     return raw === undefined ? null : raw === '' ? [] : raw.split(',');
 }
@@ -84,7 +94,18 @@ export function envScopes() {
 export function scopeAllowed(scopes, scope) {
     if (scopes === null || scopes === undefined)
         return true;
-    return scopes.some((held) => covers(held, scope));
+    return coveredByAny(scopes, scope);
+}
+/** Whether any held scope covers `scope`. A held scope equal to the request always covers it, so the
+ *  common case of a run narrowed to a subset of its grant is a string scan instead of `covers` on every
+ *  pair (a 10,000-scope grant checked against 10,000 scopes is otherwise ~15 s). A request `covers`
+ *  would reject as unparseable still throws. */
+export function coveredByAny(held, scope) {
+    if (held.includes(scope)) {
+        covers(scope, scope);
+        return true;
+    }
+    return held.some((h) => covers(h, scope));
 }
 export function envExecutionId() {
     return process.env['CRTR_EXECUTION_ID'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.440",
+  "version": "0.3.441",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",