@traffic-twin/sdk 0.0.0-stage → 0.1.0

package/dist/esm/sanitizer/policy.d.ts

@@ -0,0 +1,224 @@
+import { type KeyObject } from 'node:crypto';
+import { lexemeWithinLimits, type Plain } from './json.js';
+import { cmpUtf8 } from './utf8.js';
+export declare class Refused extends Error {
+    readonly code: 'no_policy' | 'policy_rejected' | 'expired_policy' | 'key_missing' | 'key_mismatch';
+    readonly detail: string;
+    constructor(code: 'no_policy' | 'policy_rejected' | 'expired_policy' | 'key_missing' | 'key_mismatch', detail?: string);
+}
+export declare const RESERVED_DOMAINS: Set<string>;
+export declare const BODY_FORMAT = "tt.policy.body/v1";
+export declare const ENVELOPE_FORMAT = "tt.policy.compiled/v1";
+export declare const SIGNATURE_PREFIX: Buffer<ArrayBuffer>;
+export interface Bound {
+    canon: string;
+    d: number;
+}
+export interface Action {
+    action: 'drop' | 'keep' | 'code' | 'graphql' | 'hmac' | 'bucket';
+    domain?: string;
+    kind?: 'num' | 'time';
+    bounds?: Bound[];
+    unit?: 'year' | 'month' | 'day' | 'hour';
+    /** code only (spec v1.19, sanitizer.md 5.6): the alnum shape. */
+    shape?: 'alnum';
+}
+export type Step = {
+    t: 'name';
+    name: string;
+} | {
+    t: 'any';
+} | {
+    t: 'idx';
+};
+export interface BodyRule {
+    path: string;
+    steps: Step[];
+    names: number;
+    action: Action;
+}
+export interface Part {
+    query: Map<string, Action>;
+    headers: Map<string, Action>;
+    cookies: Map<string, Action>;
+    path: Map<string, Action>;
+    body: BodyRule[];
+}
+export interface TemplateSeg {
+    lit?: string;
+    param?: string;
+}
+export interface Op {
+    key: string;
+    method: string;
+    segs: TemplateSeg[];
+    literals: number;
+    request?: Part;
+    response?: Part;
+}
+export interface Service {
+    name: string;
+    inbound: boolean;
+    internal: boolean;
+    base?: {
+        origin: string;
+        segs: string[];
+    };
+    request?: Part;
+    response?: Part;
+    errors?: Part;
+    ops: Op[];
+    /** Candidate ops by `METHOD/segment-count`, in policy order (built on first use; same result as scanning `ops`). */
+    opIndex?: Map<string, Op[]>;
+}
+export interface Limits {
+    maxBodyBytes: number;
+    maxDepth: number;
+    maxArray: number;
+    maxKeys: number;
+    keepMaxBytes: number;
+}
+/** Spec v1.19 (sanitizer.md 22.1): `bodies` of the compiled body; absent = every switch off. */
+export interface Bodies {
+    xml: boolean;
+    multipart: boolean;
+    docs: boolean;
+    maxLargeBodyBytes: number;
+    largeArray: number;
+    largeNestedArray: number;
+}
+export declare const BODIES_OFF: Bodies;
+export declare const DEFAULT_LIMITS: Limits;
+/** `jsonPath` (spec v1.18): dotted path of members inside a header whose value is a JSON object or base64/base64url of one. */
+export interface SubjectSpec {
+    from: 'header' | 'cookie';
+    name: string;
+    jwtClaim?: string;
+    jsonPath?: string;
+}
+/** Ready-to-use compiled policy. */
+export declare class Policy {
+    readonly body: {
+        [k: string]: Plain;
+    };
+    readonly policyId: string;
+    readonly version: number;
+    readonly issuedSeq: number;
+    readonly createdAt: number;
+    readonly notAfter: number;
+    readonly groups: string[];
+    readonly kid: string;
+    readonly acceptKids: string[];
+    readonly epoch: string;
+    readonly subject?: SubjectSpec;
+    readonly rateBp: number;
+    readonly trustBaggage: boolean;
+    readonly propagateTo: Set<string>;
+    readonly autoWords: boolean;
+    readonly autoWordsExpiresAt: number;
+    readonly allow: Set<string>;
+    readonly hostsAllow: Set<string>;
+    /** Spec v1.5 `hosts.discovery`: true = `auto` (default, also when `hosts` is absent), false = `off` (strict mode). */
+    readonly hostsAuto: boolean;
+    readonly limits: Limits;
+    readonly bodies: Bodies;
+    /**
+     * Bytes of a body a source keeps (sanitizer.md 9.0 and 22.5): max(max_body_bytes,
+     * bodies.max_large_body_bytes) + 1. The rest is only counted.
+     */
+    readonly captureLimit: number;
+    readonly discoveryEnabled: boolean;
+    readonly discoveryExpiresAt: number;
+    readonly global: {
+        request?: Part;
+        response?: Part;
+        errors?: Part;
+    };
+    readonly services: Service[];
+    readonly inbound: Map<string, Service>;
+    readonly baseHosts: Set<string>;
+    /** SHA-256 of the body bytes, when known (`sha256:<hex>`). */
+    hash: string;
+    /** Signed body bytes, when known: lets a worker thread rebuild this policy. */
+    bodyBytes?: Buffer;
+    constructor(body: {
+        [k: string]: Plain;
+    });
+    /** 4.3: auto words active at `now` (ms). */
+    autoWordsActive(now: number | undefined): boolean;
+    /** 15: discovery active at `now` (ms). */
+    discoveryActive(now: number | undefined): boolean;
+}
+/** RFC 3339 timestamp to epoch milliseconds; NaN when absent or malformed. */
+export declare function parseTime(v: Plain | undefined): number;
+/** Parses a tt-path; returns null if it does not follow the grammar. */
+export declare function parseTtPath(p: string): Step[] | null;
+export declare function parseOpKey(key: string): Omit<Op, 'request' | 'response'> | null;
+/** Splits a normalized `match.base` into origin and path segments. */
+export declare function splitBase(base: string): {
+    origin: string;
+    segs: string[];
+};
+/** Detail prefix of a Refused raised by the v1.3 safety subset; the agent reports it as `policy_unsafe`. */
+export declare const UNSAFE_DETAIL = "unsafe";
+/**
+ * Source-side safety subset (hardening.md 2.1, v1.3), applied to every signed body, whatever
+ * the validity of tt-core and keyguard:
+ *   H1 keep, code (v1.11, any shape) or hmac on authorization, cookie, set-cookie, proxy-authorization (header rules of
+ *      request, response and errors; global, services and operations);
+ *   H2 keep, code (v1.11) or hmac on a tt-path with any wildcard step (`.*` or `[*]`) in the global body rules;
+ *   H3 discovery or auto_words expiring later than created_at + 7 days.
+ * Properties of the body: neither the clock nor the group matter.
+ */
+export declare function checkUnsafe(b: {
+    [k: string]: Plain;
+}): void;
+/** Minimal body checks of the conformance runner (format.md, step 1), plus the v1.3 safety subset. */
+export declare function checkBodyMinimal(body: Plain): {
+    [k: string]: Plain;
+};
+/** Full schema validation of a policy body, plus reserved domains, double bounds and the v1.3 safety subset. */
+export declare function validateBodySchema(body: Plain): {
+    [k: string]: Plain;
+};
+/** Strict base64url without padding; null on any other character or impossible length. */
+export declare function b64urlDecodeStrict(s: string): Buffer | null;
+export declare function b64urlNoPad(b: Uint8Array): string;
+/** Ed25519 public key object from the raw 32 bytes (base64url, no padding). */
+export declare function ed25519PublicKey(rawB64url: string): KeyObject | null;
+export interface VerifiedPolicy {
+    bodyBytes: Buffer;
+    body: {
+        [k: string]: Plain;
+    };
+    hash: string;
+}
+/**
+ * Verifies a `tt.policy.compiled/v1` envelope (policy.md 3-4 conditions 1-2). `keys` maps a
+ * pinned, non-revoked signature kid to its public key. `strict` applies the full body
+ * schema (production); otherwise only the minimal body checks of the conformance runner.
+ */
+export declare function verifyEnvelope(env: Plain, keys: Map<string, KeyObject>, strict: boolean): VerifiedPolicy;
+/**
+ * policy.md 4, conditions 3-5: group, expiry, issued_seq ordering. `allowEqualSeq` lets a
+ * source re-verify the very policy it already accepted (cache at start-up).
+ */
+export declare function checkAcceptance(p: Policy, o: {
+    group: string;
+    now: number;
+    lastIssuedSeq: number;
+    minIssuedSeq: number;
+    allowEqualSeq?: boolean;
+}): void;
+export interface KeyRing {
+    keys: Map<string, Buffer>;
+    order: string[];
+}
+/** Parses the content of TT_HMAC_KEY / TT_HMAC_KEY_FILE. Throws Refused('key_missing'). */
+export declare function parseKeyRing(text: string | undefined | null): KeyRing;
+/** 7.1: picks the key for a policy (hmac.kid, then accept_kids in order). */
+export declare function selectKey(ring: KeyRing, policy: Policy): {
+    kid: string;
+    key: Buffer;
+};
+export { cmpUtf8, lexemeWithinLimits };