@vouchington/utils 0.5.1 → 0.5.2

package/README.md

@@ -11,10 +11,16 @@ import { buildSignatureHeaders, verifySignature } from '@vouchington/utils/http-
 import { bestAcceptLanguageMatch } from '@vouchington/utils/language-tags'
 import { createMessageTranslator } from '@vouchington/utils/message-catalog'
 import { createReportInputParser } from '@vouchington/utils/moderation'
+import { getSentryEnvelopeDiagnostics } from '@vouchington/utils/sentry-envelope'
+import { createScopeCatalog } from '@vouchington/utils/scopes'
 ```
 
 ## Subpaths
 
+- `sentry-envelope`: bounded UTF-8 envelope record scanning and safe item-type diagnostics.
+  Callers choose the byte and type-list limits; DSN, tunnel, request, and logging policy stay local.
+- `scopes`: caller-owned scope catalog validation, prerequisite expansion, audience and surface
+  filtering, and explicit coverage graph calculation. No default catalog or legacy grants are built in.
 - `token-secrets`: Node-only (`node:crypto`) purpose-bound HMAC and AES-256-GCM encryption.
   `createTokenSecrets({ hashSecret, encryptionKeys })` throws for invalid keys or ciphertext.
 - `deploy-environment`: `getDeployEnvironment(source)` classifies explicit environment inputs without

package/dist/scopes.d.mts

@@ -0,0 +1,29 @@
+export interface ScopeDefinition {
+    audience: string;
+    surfaces: readonly string[];
+    requires?: readonly string[];
+    covers?: readonly string[];
+}
+export type ScopeValidationCode = 'duplicate-scope' | 'empty-scope-set' | 'missing-prerequisite' | 'mixed-audiences' | 'unsupported-surface' | 'unknown-scope';
+export type ScopeValidationResult = {
+    valid: true;
+    scopes: string[];
+    audiences: string[];
+} | {
+    valid: false;
+    code: ScopeValidationCode;
+    scope?: string;
+    requiredScope?: string;
+};
+export interface ScopeCatalog {
+    hasScope(granted: readonly string[], required: string): boolean;
+    hasEveryScope(granted: readonly string[], required: readonly string[]): boolean;
+    expandPrerequisites(scopes: readonly string[]): string[];
+    listScopesForAudience(audience: string, surface: string): string[];
+    validateScopeSet(input: readonly string[], options: {
+        surface: string;
+        allowMixedAudiences: boolean;
+    }): ScopeValidationResult;
+}
+/** Compile a caller-owned scope graph; product grant and authorization decisions stay in callers. */
+export declare function createScopeCatalog(definitions: Record<string, ScopeDefinition>): ScopeCatalog;

package/dist/scopes.mjs

@@ -0,0 +1,122 @@
+/** Compile a caller-owned scope graph; product grant and authorization decisions stay in callers. */
+export function createScopeCatalog(definitions) {
+    const catalog = new Map();
+    for (const [scope, definition] of Object.entries(definitions)) {
+        if (!scope ||
+            !definition ||
+            typeof definition.audience !== 'string' ||
+            !definition.audience ||
+            !Array.isArray(definition.surfaces) ||
+            definition.surfaces.length === 0 ||
+            definition.surfaces.some((surface) => typeof surface !== 'string' || !surface)) {
+            throw new TypeError(`Invalid scope definition for ${scope}`);
+        }
+        for (const edges of [definition.requires, definition.covers]) {
+            if (edges !== undefined &&
+                (!Array.isArray(edges) || edges.some((edge) => typeof edge !== 'string' || !edge))) {
+                throw new TypeError(`Invalid scope edges for ${scope}`);
+            }
+        }
+        catalog.set(scope, {
+            audience: definition.audience,
+            surfaces: [...definition.surfaces],
+            requires: [...(definition.requires ?? [])],
+            covers: [...(definition.covers ?? [])],
+        });
+    }
+    for (const relation of ['requires', 'covers'])
+        assertAcyclic(catalog, relation);
+    function requireScope(scope) {
+        const definition = catalog.get(scope);
+        if (!definition)
+            throw new RangeError(`Unknown scope: ${scope}`);
+        return definition;
+    }
+    function expandPrerequisites(scopes) {
+        const expanded = new Set();
+        function visit(scope) {
+            if (expanded.has(scope))
+                return;
+            const definition = requireScope(scope);
+            expanded.add(scope);
+            for (const required of definition.requires)
+                visit(required);
+        }
+        for (const scope of scopes)
+            visit(scope);
+        return [...expanded].sort();
+    }
+    function covers(granted, required, visited) {
+        if (granted === required)
+            return true;
+        if (visited.has(granted))
+            return false;
+        visited.add(granted);
+        return requireScope(granted).covers.some((scope) => covers(scope, required, visited));
+    }
+    function hasScope(granted, required) {
+        requireScope(required);
+        return granted.some((scope) => covers(scope, required, new Set()));
+    }
+    return {
+        expandPrerequisites,
+        hasScope,
+        hasEveryScope(granted, required) {
+            return required.every((scope) => hasScope(granted, scope));
+        },
+        listScopesForAudience(audience, surface) {
+            return [...catalog]
+                .filter(([, definition]) => definition.audience === audience && definition.surfaces.includes(surface))
+                .map(([scope]) => scope)
+                .sort();
+        },
+        validateScopeSet(input, options) {
+            if (input.length === 0)
+                return { valid: false, code: 'empty-scope-set' };
+            const seen = new Set();
+            for (const scope of input) {
+                const definition = catalog.get(scope);
+                if (!definition)
+                    return { valid: false, code: 'unknown-scope', scope };
+                if (seen.has(scope))
+                    return { valid: false, code: 'duplicate-scope', scope };
+                if (!definition.surfaces.includes(options.surface)) {
+                    return { valid: false, code: 'unsupported-surface', scope };
+                }
+                seen.add(scope);
+            }
+            const scopes = [...seen].sort();
+            for (const scope of scopes) {
+                for (const requiredScope of requireScope(scope).requires) {
+                    if (!seen.has(requiredScope)) {
+                        return { valid: false, code: 'missing-prerequisite', scope, requiredScope };
+                    }
+                }
+            }
+            const audiences = [...new Set(scopes.map((scope) => requireScope(scope).audience))].sort();
+            if (!options.allowMixedAudiences && audiences.length > 1) {
+                return { valid: false, code: 'mixed-audiences' };
+            }
+            return { valid: true, scopes, audiences };
+        },
+    };
+}
+function assertAcyclic(catalog, relation) {
+    const done = new Set();
+    const active = new Set();
+    function visit(scope) {
+        if (!catalog.has(scope))
+            throw new RangeError(`Unknown ${relation} scope: ${scope}`);
+        if (active.has(scope))
+            throw new RangeError(`Scope ${relation} cycle at ${scope}`);
+        if (done.has(scope))
+            return;
+        active.add(scope);
+        for (const next of catalog.get(scope)[relation])
+            visit(next);
+        active.delete(scope);
+        done.add(scope);
+    }
+    for (const scope of catalog.keys())
+        visit(scope);
+}

package/dist/sentry-envelope.d.mts

@@ -0,0 +1,10 @@
+export interface SentryEnvelopeDiagnostics {
+    envelopeItemCount?: number;
+    envelopeItemTypes?: string[];
+}
+export interface SentryEnvelopeLimits {
+    maxBytes: number;
+    maxItemTypes: number;
+}
+/** Read bounded envelope item metadata without inspecting payload content. */
+export declare function getSentryEnvelopeDiagnostics(envelope: string, limits: SentryEnvelopeLimits): SentryEnvelopeDiagnostics;

package/dist/sentry-envelope.mjs

@@ -0,0 +1,82 @@
+const ITEM_TYPE_PATTERN = /^[a-z0-9_.-]{1,64}$/;
+/** Read bounded envelope item metadata without inspecting payload content. */
+export function getSentryEnvelopeDiagnostics(envelope, limits) {
+    if (!Number.isSafeInteger(limits.maxBytes) || limits.maxBytes < 1) {
+        throw new RangeError('maxBytes must be a positive safe integer');
+    }
+    if (!Number.isSafeInteger(limits.maxItemTypes) || limits.maxItemTypes < 0) {
+        throw new RangeError('maxItemTypes must be a non-negative safe integer');
+    }
+    if (envelope.length > limits.maxBytes ||
+        new TextEncoder().encode(envelope).length > limits.maxBytes) {
+        throw new RangeError('Envelope exceeds maxBytes');
+    }
+    const firstLineEnd = envelope.indexOf('\n');
+    if (firstLineEnd === -1)
+        return {};
+    const itemTypes = [];
+    let itemCount = 0;
+    let cursor = firstLineEnd + 1;
+    while (cursor < envelope.length) {
+        if (envelope[cursor] === '\n') {
+            cursor += 1;
+            continue;
+        }
+        const itemHeaderEnd = envelope.indexOf('\n', cursor);
+        if (itemHeaderEnd === -1)
+            break;
+        const line = envelope.slice(cursor, itemHeaderEnd).replace(/\r$/, '');
+        cursor = itemHeaderEnd + 1;
+        if (!line)
+            continue;
+        let header;
+        try {
+            header = JSON.parse(line);
+        }
+        catch {
+            break;
+        }
+        if (!header || typeof header !== 'object' || Array.isArray(header))
+            break;
+        itemCount += 1;
+        const type = header.type;
+        if (typeof type === 'string' &&
+            ITEM_TYPE_PATTERN.test(type) &&
+            !itemTypes.includes(type) &&
+            itemTypes.length < limits.maxItemTypes) {
+            itemTypes.push(type);
+        }
+        const length = header.length;
+        if (typeof length === 'number' && Number.isSafeInteger(length) && length >= 0) {
+            const next = advanceByUtf8Bytes(envelope, cursor, length);
+            if (next === null)
+                break;
+            cursor = next;
+            if (envelope[cursor] === '\r' && envelope[cursor + 1] === '\n')
+                cursor += 2;
+            else if (envelope[cursor] === '\n')
+                cursor += 1;
+            continue;
+        }
+        const payloadEnd = envelope.indexOf('\n', cursor);
+        if (payloadEnd === -1)
+            break;
+        cursor = payloadEnd + 1;
+    }
+    return {
+        ...(itemCount > 0 ? { envelopeItemCount: itemCount } : {}),
+        ...(itemTypes.length > 0 ? { envelopeItemTypes: itemTypes } : {}),
+    };
+}
+function advanceByUtf8Bytes(envelope, cursor, length) {
+    let bytes = 0;
+    while (cursor < envelope.length && bytes < length) {
+        const point = envelope.codePointAt(cursor);
+        const size = point <= 0x7f ? 1 : point <= 0x7ff ? 2 : point <= 0xffff ? 3 : 4;
+        if (bytes + size > length)
+            return null;
+        bytes += size;
+        cursor += point > 0xffff ? 2 : 1;
+    }
+    return bytes === length ? cursor : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/utils",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Dependency-free runtime utilities for Vouchington-style applications.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/utils#readme",
   "bugs": {
@@ -20,6 +20,16 @@
   ],
   "type": "module",
   "exports": {
+    "./sentry-envelope": {
+      "types": "./dist/sentry-envelope.d.mts",
+      "import": "./dist/sentry-envelope.mjs",
+      "default": "./dist/sentry-envelope.mjs"
+    },
+    "./scopes": {
+      "types": "./dist/scopes.d.mts",
+      "import": "./dist/scopes.mjs",
+      "default": "./dist/scopes.mjs"
+    },
     "./token-secrets": {
       "types": "./dist/token-secrets.d.mts",
       "import": "./dist/token-secrets.mjs",