@shieldaai/agent-map 0.1.0-alpha.2 → 1.0.0

package/dist/oidc.js

@@ -2,9 +2,10 @@ import { request as httpsRequest } from 'node:https';
 import { lookup } from 'node:dns';
 import { X509Certificate } from 'node:crypto';
 import { rootCertificates, createSecureContext } from 'node:tls';
-import { immutableJson } from '@shieldaai/agent-guard';
+import { immutableJson } from '@shieldaai/agent-guard/internal';
 import * as oidc from 'openid-client';
-import { fields, integer, fail, parseRequest } from './boundary.js';
+import { integer, fail } from './common.js';
+import { fields, parseRequest } from './boundary.js';
 import { MapQueryError, mapIdentifier } from './types.js';
 const INVALID = 'MAP_IDENTITY_INVALID', UNAVAILABLE = 'MAP_IDENTITY_UNAVAILABLE';
 function httpsUrl(value, code, query = false) {
@@ -35,8 +36,18 @@ export async function createMapOidcClient(options) {
     catch {
         return fail('MAP_CONFIG_INVALID');
     }
-    const config = fields(copied, ['issuer', 'clientId', 'clientSecret', 'redirectUri', 'clientAuthMethod',
-        'endpointOrigins', 'ca', 'requestTimeoutMs', 'maxResponseBytes'], ['issuer', 'clientId', 'clientSecret', 'redirectUri']);
+    const config = fields(copied, [
+        'issuer',
+        'clientId',
+        'clientSecret',
+        'redirectUri',
+        'clientAuthMethod',
+        'endpointOrigins',
+        'ca',
+        'requestTimeoutMs',
+        'maxResponseBytes',
+        'clockToleranceSeconds',
+    ], ['issuer', 'clientId', 'clientSecret', 'redirectUri']);
     const issuer = httpsUrl(config.issuer, 'MAP_CONFIG_INVALID');
     if (issuer.pathname.includes('/.well-known/'))
         fail('MAP_CONFIG_INVALID');
@@ -53,6 +64,9 @@ export async function createMapOidcClient(options) {
     const authentication = () => method === 'client_secret_basic' ? oidc.ClientSecretBasic(secret) : oidc.ClientSecretPost(secret);
     const timeout = integer(config.requestTimeoutMs, 5000, 50, 10_000);
     const maxBytes = integer(config.maxResponseBytes, 256 * 1024, 1024, 1024 * 1024);
+    // An identity provider's clock is rarely the same second as ours. The tolerance lets a token
+    // issued (or valid from) slightly in our future through; expiry is checked below without it.
+    const clockTolerance = integer(config.clockToleranceSeconds, 5, 0, 60);
     const origins = new Set([issuer.origin]);
     if (config.endpointOrigins !== undefined) {
         if (!Array.isArray(config.endpointOrigins) || config.endpointOrigins.length > 8)
@@ -69,7 +83,9 @@ export async function createMapOidcClient(options) {
         if (typeof config.ca !== 'string' || !config.ca || Buffer.byteLength(config.ca) > 256 * 1024)
             fail('MAP_CONFIG_INVALID');
         const certificates = config.ca.match(/-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/g);
-        if (!certificates?.length || certificates.length > 16 || config.ca.replace(/-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/g, '').trim())
+        if (!certificates?.length ||
+            certificates.length > 16 ||
+            config.ca.replace(/-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/g, '').trim())
             fail('MAP_CONFIG_INVALID');
         try {
             for (const certificate of certificates)
@@ -90,8 +106,10 @@ export async function createMapOidcClient(options) {
     function operation(external) {
         const deadline = performance.now() + timeout, active = new Set();
         let closed = false, failure;
-        const check = () => { if (closed || external?.aborted || performance.now() >= deadline)
-            fail(UNAVAILABLE); };
+        const check = () => {
+            if (closed || external?.aborted || performance.now() >= deadline)
+                fail(UNAVAILABLE);
+        };
         const fetch = (input, init) => new Promise((resolve, reject) => {
             let request, settled = false, counted = false;
             let timer;
@@ -154,17 +172,30 @@ export async function createMapOidcClient(options) {
                             callback(error, addresses?.[0]?.address ?? '', addresses?.[0]?.family);
                     });
                 };
-                request = httpsRequest(url, { method: init.method, headers: { ...init.headers, 'accept-encoding': 'identity', connection: 'close' },
-                    agent: false, rejectUnauthorized: true, minVersion: 'TLSv1.2', maxHeaderSize: 8192,
-                    lookup: boundedLookup, ...(ca === undefined ? {} : { ca }) }, response => {
+                request = httpsRequest(url, {
+                    method: init.method,
+                    headers: { ...init.headers, 'accept-encoding': 'identity', connection: 'close' },
+                    agent: false,
+                    rejectUnauthorized: true,
+                    minVersion: 'TLSv1.2',
+                    maxHeaderSize: 8192,
+                    lookup: boundedLookup,
+                    ...(ca === undefined ? {} : { ca }),
+                }, response => {
                     const status = response.statusCode ?? 0;
                     const count = (name) => response.rawHeaders.filter((item, index) => index % 2 === 0 && item.toLowerCase() === name).length;
                     const length = response.headers['content-length'];
-                    if ((status >= 300 && status < 400) || status >= 500 || status < 200 ||
-                        count('content-length') > 1 || count('content-type') !== 1 || count('transfer-encoding') > 1 ||
-                        response.headers['content-encoding'] !== undefined || (length !== undefined && response.headers['transfer-encoding'] !== undefined) ||
+                    if ((status >= 300 && status < 400) ||
+                        status >= 500 ||
+                        status < 200 ||
+                        count('content-length') > 1 ||
+                        count('content-type') !== 1 ||
+                        count('transfer-encoding') > 1 ||
+                        response.headers['content-encoding'] !== undefined ||
+                        (length !== undefined && response.headers['transfer-encoding'] !== undefined) ||
                         !/^application\/(?:json|jwk-set\+json)(?:\s*;\s*charset=utf-8)?$/i.test(response.headers['content-type'] ?? '') ||
-                        (length !== undefined && (!/^\d+$/.test(length) || !Number.isSafeInteger(Number(length)) || Number(length) > maxBytes))) {
+                        (length !== undefined &&
+                            (!/^\d+$/.test(length) || !Number.isSafeInteger(Number(length)) || Number(length) > maxBytes))) {
                         response.destroy();
                         stop(UNAVAILABLE);
                         return;
@@ -221,30 +252,53 @@ export async function createMapOidcClient(options) {
                 stop(error instanceof MapQueryError ? error.code : UNAVAILABLE);
             }
         });
-        return { fetch, check, get failure() { return failure; }, close() { closed = true; for (const request of active)
-                request.destroy(); } };
+        return {
+            fetch,
+            check,
+            get failure() {
+                return failure;
+            },
+            close() {
+                closed = true;
+                for (const request of active)
+                    request.destroy();
+            },
+        };
     }
-    const clientMetadata = { id_token_signed_response_alg: 'RS256', [oidc.clockTolerance]: 0 };
+    const clientMetadata = { id_token_signed_response_alg: 'RS256', [oidc.clockTolerance]: clockTolerance };
     const discovery = operation();
     let metadata;
     try {
-        const discovered = await oidc.discovery(issuer, clientId, clientMetadata, authentication(), { [oidc.customFetch]: discovery.fetch, timeout: timeout / 1000 });
+        const discovered = await oidc.discovery(issuer, clientId, clientMetadata, authentication(), {
+            [oidc.customFetch]: discovery.fetch,
+            timeout: timeout / 1000,
+        });
         discovery.check();
         const remote = discovered.serverMetadata();
-        if (remote.issuer !== config.issuer || !Array.isArray(remote.id_token_signing_alg_values_supported) ||
+        if (remote.issuer !== config.issuer ||
+            !Array.isArray(remote.id_token_signing_alg_values_supported) ||
             !remote.id_token_signing_alg_values_supported.includes('RS256') ||
-            !Array.isArray(remote.code_challenge_methods_supported) || !remote.code_challenge_methods_supported.includes('S256') ||
-            (remote.token_endpoint_auth_methods_supported === undefined ? method !== 'client_secret_basic' :
-                !Array.isArray(remote.token_endpoint_auth_methods_supported) || !remote.token_endpoint_auth_methods_supported.includes(method)))
+            !Array.isArray(remote.code_challenge_methods_supported) ||
+            !remote.code_challenge_methods_supported.includes('S256') ||
+            (remote.token_endpoint_auth_methods_supported === undefined
+                ? method !== 'client_secret_basic'
+                : !Array.isArray(remote.token_endpoint_auth_methods_supported) ||
+                    !remote.token_endpoint_auth_methods_supported.includes(method)))
             fail(INVALID);
         for (const name of ['authorization_endpoint', 'token_endpoint', 'jwks_uri']) {
             if (!origins.has(httpsUrl(remote[name], INVALID).origin))
                 fail(INVALID);
         }
-        metadata = { issuer: remote.issuer, authorization_endpoint: remote.authorization_endpoint,
-            token_endpoint: remote.token_endpoint, jwks_uri: remote.jwks_uri, id_token_signing_alg_values_supported: ['RS256'],
-            code_challenge_methods_supported: ['S256'], token_endpoint_auth_methods_supported: [method],
-            authorization_response_iss_parameter_supported: remote.authorization_response_iss_parameter_supported === true };
+        metadata = {
+            issuer: remote.issuer,
+            authorization_endpoint: remote.authorization_endpoint,
+            token_endpoint: remote.token_endpoint,
+            jwks_uri: remote.jwks_uri,
+            id_token_signing_alg_values_supported: ['RS256'],
+            code_challenge_methods_supported: ['S256'],
+            token_endpoint_auth_methods_supported: [method],
+            authorization_response_iss_parameter_supported: remote.authorization_response_iss_parameter_supported === true,
+        };
     }
     catch (error) {
         throw discovery.failure ?? new MapQueryError(error instanceof MapQueryError ? error.code : INVALID);
@@ -264,8 +318,15 @@ export async function createMapOidcClient(options) {
             const op = operation();
             try {
                 const state = oidc.randomState(), nonce = oidc.randomNonce(), codeVerifier = oidc.randomPKCECodeVerifier();
-                const authorizationUrl = oidc.buildAuthorizationUrl(configuration(op.fetch), { response_type: 'code', scope: 'openid',
-                    redirect_uri: redirect.href, state, nonce, code_challenge_method: 'S256', code_challenge: await oidc.calculatePKCECodeChallenge(codeVerifier) });
+                const authorizationUrl = oidc.buildAuthorizationUrl(configuration(op.fetch), {
+                    response_type: 'code',
+                    scope: 'openid',
+                    redirect_uri: redirect.href,
+                    state,
+                    nonce,
+                    code_challenge_method: 'S256',
+                    code_challenge: await oidc.calculatePKCECodeChallenge(codeVerifier),
+                });
                 op.check();
                 return Object.freeze({ authorizationUrl: authorizationUrl.href, state, nonce, codeVerifier });
             }
@@ -280,28 +341,50 @@ export async function createMapOidcClient(options) {
             const op = operation(signal);
             try {
                 op.check();
-                if (!(callbackUrl instanceof URL) || callbackUrl.href.length > 8192 || callbackUrl.origin !== redirect.origin ||
-                    callbackUrl.pathname !== redirect.pathname || callbackUrl.hash || callbackUrl.username || callbackUrl.password)
+                if (!(callbackUrl instanceof URL) ||
+                    callbackUrl.href.length > 8192 ||
+                    callbackUrl.origin !== redirect.origin ||
+                    callbackUrl.pathname !== redirect.pathname ||
+                    callbackUrl.hash ||
+                    callbackUrl.username ||
+                    callbackUrl.password)
                     fail(INVALID);
                 const callback = new URL(callbackUrl.href), names = [...callback.searchParams.keys()];
-                if (names.length > 16 || new Set(names).size !== names.length || names.some(name => !name || name.length > 128) ||
-                    callback.searchParams.get('error') !== null || callback.searchParams.get('response') !== null ||
-                    !callback.searchParams.get('code') || !callback.searchParams.get('state'))
+                if (names.length > 16 ||
+                    new Set(names).size !== names.length ||
+                    names.some(name => !name || name.length > 128) ||
+                    callback.searchParams.get('error') !== null ||
+                    callback.searchParams.get('response') !== null ||
+                    !callback.searchParams.get('code') ||
+                    !callback.searchParams.get('state'))
                     fail(INVALID);
                 const value = fields(transaction, ['state', 'nonce', 'codeVerifier'], ['state', 'nonce', 'codeVerifier']);
                 const state = opaque(value.state), nonce = opaque(value.nonce), verifier = opaque(value.codeVerifier);
-                const tokens = await oidc.authorizationCodeGrant(configuration(op.fetch), callback, { expectedState: state, expectedNonce: nonce, pkceCodeVerifier: verifier, idTokenExpected: true });
+                const tokens = await oidc.authorizationCodeGrant(configuration(op.fetch), callback, {
+                    expectedState: state,
+                    expectedNonce: nonce,
+                    pkceCodeVerifier: verifier,
+                    idTokenExpected: true,
+                });
                 op.check();
                 const claims = tokens.claims(), now = Date.now();
-                if (!claims || claims.iss !== config.issuer || (claims.azp !== undefined && claims.azp !== clientId) ||
-                    !Number.isSafeInteger(claims.exp) || !Number.isSafeInteger(claims.iat) || claims.iat > Math.floor(now / 1000) ||
-                    claims.exp <= claims.iat || !Number.isSafeInteger(claims.exp * 1000) || claims.exp * 1000 <= now)
+                if (!claims ||
+                    claims.iss !== config.issuer ||
+                    (claims.azp !== undefined && claims.azp !== clientId) ||
+                    !Number.isSafeInteger(claims.exp) ||
+                    !Number.isSafeInteger(claims.iat) ||
+                    claims.iat > Math.floor(now / 1000) + clockTolerance ||
+                    claims.exp <= claims.iat ||
+                    !Number.isSafeInteger(claims.exp * 1000) ||
+                    // The protocol library's tolerance also covers `exp`; this check does not.
+                    claims.exp * 1000 <= now)
                     fail(INVALID);
                 const subject = mapIdentifier(claims.sub, INVALID);
                 return Object.freeze({ subject, expiresAt: claims.exp * 1000 });
             }
             catch (error) {
-                throw op.failure ?? new MapQueryError(error instanceof MapQueryError && error.code === UNAVAILABLE ? UNAVAILABLE : INVALID);
+                throw (op.failure ??
+                    new MapQueryError(error instanceof MapQueryError && error.code === UNAVAILABLE ? UNAVAILABLE : INVALID));
             }
             finally {
                 op.close();

package/dist/policy-reader.d.ts

@@ -1,4 +1,4 @@
-import { type JsonObject, type MapEdge, type MapNode, type MapPolicyCandidate, type MapPolicyEvidence } from './types.js';
+import { type JsonObject, type MapEdge, type MapNode, type MapPolicyCandidate, type MapPolicyEvidence, type MapPolicySelection, type MapIdentityScope } from './types.js';
 interface Probe {
     readonly key: number;
     readonly identity: MapNode;
@@ -17,12 +17,65 @@ export interface PolicyPlan {
     readonly records: readonly MapPolicyEvidence[];
     readonly probes: readonly Probe[];
 }
-/** Pair only the selected task's grants with its deployment's declared execution identity. */
-export declare function policyPlan(companyId: string, tenantId: string, nodes: readonly MapNode[], edges: readonly MapEdge[], maximum: number): PolicyPlan;
+/** Python's scope ID uses compact ensure_ascii JSON; preserve that byte contract. */
+export declare function collectionKey(companyId: string, tenantId: string, partition: string, accountId: string): string;
+/**
+ * Pair only the selected task's grants with its deployment's declared execution identity.
+ * `select` narrows the pairs to one task, tool, resource reference (or mapped ARN) or action,
+ * so a read that shows a few pairs is not bound by the size of the whole fleet.
+ */
+export declare function policyPlan(companyId: string, tenantId: string, nodes: readonly MapNode[], edges: readonly MapEdge[], maximum: number, select?: MapPolicySelection): PolicyPlan;
 export declare const POLICY_QUERY: string;
 export declare const POLICY_COLUMNS: readonly ['key', 'bindingProof', 'identity', 'resource', 'identityLink', 'resourceLink', 'principal', 'bucket', 'principalAccount', 'bucketAccount', 'principalOwnership', 'bucketOwnership', 'collection', 'principalMember', 'bucketMember', 'candidate'];
 export declare function policyParameters(plan: PolicyPlan): readonly Record<string, unknown>[];
 export declare function safePolicyRow(raw: unknown): JsonObject;
 /** Pure classification: no positive candidate survives a malformed endpoint or stale receipt. */
 export declare function policyEvidence(plan: PolicyPlan, rows: readonly JsonObject[], now: number, maximumAge: number): readonly MapPolicyEvidence[];
+/** Buckets listed per identity before the comparison reports `truncated`. */
+export declare const IDENTITY_SCOPE_BUCKETS = 500;
+interface ScopeProbe {
+    readonly key: number;
+    readonly identity: MapNode;
+    readonly accountId: string;
+    readonly partition: string;
+    readonly principalArn: string;
+    readonly principalLabel: 'AWSRole' | 'AWSUser';
+    readonly collectionId: string;
+    readonly proof: Readonly<Record<string, string | null>>;
+}
+/** One execution binding's comparison against its identity's probe. */
+interface ScopeLink {
+    readonly record: number;
+    readonly probe: number;
+    /** Buckets this tool's live grants bind as a whole bucket. */
+    readonly bound: ReadonlySet<string>;
+    /** Buckets bound only as an object or prefix: a bucket-level candidate may reach further. */
+    readonly partial: ReadonlySet<string>;
+}
+export interface IdentityScopePlan {
+    readonly records: readonly MapIdentityScope[];
+    /** One probe per distinct identity; several tools sharing a role share its probe. */
+    readonly probes: readonly ScopeProbe[];
+    readonly links: readonly ScopeLink[];
+    /** Only these bucket names are read, or every collected bucket when null. */
+    readonly buckets: readonly string[] | null;
+    /** Distinct buckets kept per identity before it reports `truncated`. */
+    readonly bucketLimit: number;
+    /** Rows read per identity; one past the expected maximum marks a longer list. */
+    readonly candidateLimit: number;
+}
+/**
+ * One record per execution binding; a probe per distinct, unambiguous, resolved static AWS
+ * identity. Past `maximum` identities the rest report `not_evaluated` instead of failing the
+ * read. `buckets` limits the read to those bucket names (the reach check behind
+ * `list_resources`). Grants count only on live tasks at `observedAt` (the snapshot time).
+ */
+export declare function identityScopePlan(companyId: string, tenantId: string, nodes: readonly MapNode[], edges: readonly MapEdge[], maximum: number, buckets?: readonly string[] | null, observedAt?: number): IdentityScopePlan;
+export declare const IDENTITY_SCOPE_QUERY: string;
+export declare const IDENTITY_SCOPE_COLUMNS: readonly ['key', 'executionProof', 'identity', 'identityLink', 'principal', 'principalAccount', 'principalOwnership', 'collection', 'principalMember', 'candidates'];
+export declare function identityScopeParameters(plan: IdentityScopePlan): readonly Record<string, unknown>[];
+export declare function safeIdentityScopeRow(raw: unknown): JsonObject;
+export declare function identityScopeEvidence(plan: IdentityScopePlan, rows: readonly JsonObject[], now: number, maximumAge: number, 
+/** For a team-scoped reader: the only bucket names it may see; null for an all-teams reader. */
+readable?: ReadonlySet<string> | null): readonly MapIdentityScope[];
 export {};