@coderifts/agent-guard 9.5.0 → 9.7.0

package/README.md

@@ -174,17 +174,22 @@ When `withCodeRifts({ executorAttestation: { registry } })` is set and a CAS out
 > binder needed). A custom binder is still required only when the content lives under a different
 > argument name or must be resolved from `filesTouched`/`diff`.
 
-### Guarding the whole tool surface (inescapability)
+### Guarding the whole tool surface (registry scope)
 
-`guardToolCall` guards one call. To make CodeRifts the **only** path a mutating tool can take, wrap
-your entire tool list with [`guardToolRegistry`](#) — it returns the sole tool table the agent may
-see (every mutator wrapped, fail-closed at construction if any would remain raw):
+`guardToolCall` guards one call. [`guardToolRegistry`](#) takes your whole tool list and returns a
+table in which every mutator is wrapped, failing closed at construction if any would remain raw.
+What that buys is a property of **the returned table**, not of the agent: register only this table,
+and no mutator *in it* is reachable raw. Tools the host registers elsewhere are outside the guard —
+see **The two scopes** below for how `registry_report` and `composition_assurance` answer those two
+different questions.
 
 ```typescript
 import { guardToolRegistry } from '@coderifts/agent-guard';
 
 const { tools, coverage } = guardToolRegistry(rawTools, { guard: { client } });
-// register ONLY `tools` with your agent SDK; coverage === 'COMPLETE' ⇒ no mutator is reachable raw.
+// register ONLY `tools`; coverage === 'COMPLETE' ⇒ no mutator IN THIS TABLE is reachable raw.
+// That is table-truth, not a coverage claim about live traffic: for what was actually
+// observed this run, read `composition_assurance.observed_class`.
 ```
 
 ### One-call orchestration with `withCodeRifts` (S1 + S2)
@@ -250,6 +255,41 @@ const { tools, registry_report, composition_assurance, receipt_thread } = withCo
 // register ONLY `tools`. Receipt carry-forward is default-on (`receipt_thread`).
 ```
 
+### Native execution grant (`executionGrant`, 9.6.0)
+
+`withCodeRifts` 9.5.0 could not request a grant: its authorize sent four
+fields and the factory received `decision_result`, so a top-level
+`execution_grant` was dropped. The interim app-side wrap
+(`withExecutionGrantClient` / `takeGrant()`) worked but was **last-authorize**
+— overlapping tool calls could hand a tool the wrong grant.
+
+9.6.0 closes that natively. Default **OFF** (absent config is byte-identical
+to 9.5.0). A host on 9.6.0 does **not** need `withExecutionGrantClient`.
+
+```typescript
+const { tools } = withCodeRifts({
+  tools: rawTools, // execute(args, { execution_grant }) — 2nd arg is THIS call's grant
+  client,
+  operation: 'merge',
+  executionGrant: {
+    enabled: true,
+    // Optional. Return the ATOMIC nonce for THIS call (customer executor
+    // state-challenge). A throw fails the call closed
+    // (EXECUTION_GRANT_NONCE_UNRESOLVABLE) — never a grant-less proceed.
+    resolveStateNonce: async ({ artifactId, toolName, args }) =>
+      challengeNonceFor(artifactId),
+  },
+});
+```
+
+`guardToolCall` factory 3rd argument is the same `{ execution_grant }` object,
+scoped to that invocation. Allow-class authorize that requested a grant and
+does not receive one fails closed (`EXECUTION_GRANT_MISSING` /
+`SIGNER_UNAVAILABLE`). After a grant was requested, `failPolicy: 'open'`
+does not OPEN_PASSTHROUGH grant-less — the call fails closed with the
+server's reason. The outcome records `{ requested, arrived }` only —
+not the token. Not a verdict input; not a preimage field.
+
 Honesty (do not over-claim):
 
 - **Freshness** is ACTIVE only because STRICT sets `requireFreshness` **and** you supplied
@@ -927,6 +967,15 @@ Pass claim+lifecycle on `withCodeRifts({ …, onEvent, monitoringSinkWired: true
 - **Integrity failures never fail open** — a bad signature, schema-invalid response, detector/config
   error, or request-attributable rejection (413/422) always resolves closed + trips the breaker.
 
+**The artifact is not the contract.** Every guarantee above keys off a change to a contract *file*.
+An implementation edit under an unchanged spec changes the served behaviour and produces nothing for
+this package to see: the detector does not trigger, no preflight fires, and a clean run means only
+that the artifact did not move. A handler that starts returning `null` for a field the schema still
+marks required, a response that quietly changes shape, an authorization check deleted behind a
+byte-identical OpenAPI file — none of those are contract changes as far as this package is
+concerned, and none of them are caught here. Governing the artifact is not the same as governing the
+behaviour it describes, and this package does not diff served behaviour.
+
 ## Trigger detection
 
 `builtinDetector` (fail-safe, versioned) decides whether a tool call touches a contract artifact

package/dist/cjs/coverage-attestation.d.ts

@@ -0,0 +1,27 @@
+import type { CoverageObserved } from './coverage-observed.js';
+export declare const COVERAGE_ATTEST_VERSION = "cr.coverage.attest.v1";
+export declare const COVERAGE_ATTEST_SIGNING_PREFIX = "crcovattest.v1";
+export declare const COVERAGE_ATTEST_ENVELOPE_TAG = "cr.coverage.attest.v1";
+export type CoverageAttestationSigner = (bytes: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+export type CoverageAttestationConfig = {
+    /** Customer-held coverage key id. Named on the token; resolved later against a registry. */
+    kid: string;
+    /** Host signs the UTF-8 signing-input bytes. Returns raw Ed25519 signature. Never a raw key. */
+    signer: CoverageAttestationSigner;
+    /** Scope label for the statement (e.g. a session id). Required — a statement needs a subject. */
+    sessionId: string;
+};
+export declare function coverageAttestSigningInput(body: Record<string, unknown>): string;
+/**
+ * Issue a cr.coverage.attest.v1 token from a coverage snapshot. Returns undefined when config is
+ * absent, the snapshot is unusable, or the host signer throws — never an unsigned token.
+ */
+export declare function tryIssueCoverageAttestation(args: {
+    config?: CoverageAttestationConfig | null;
+    coverage: CoverageObserved | null | undefined;
+    decisionId?: string | null;
+    receiptDigest?: string | null;
+    now?: string;
+}): Promise<string | undefined>;
+export declare function kidFromCoverageAttestation(token: string | undefined | null): string | null;
+//# sourceMappingURL=coverage-attestation.d.ts.map

package/dist/cjs/coverage-attestation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-attestation.d.ts","sourceRoot":"","sources":["../../src/coverage-attestation.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,eAAO,MAAM,uBAAuB,0BAA0B,CAAC;AAC/D,eAAO,MAAM,8BAA8B,mBAAmB,CAAC;AAC/D,eAAO,MAAM,4BAA4B,0BAA0B,CAAC;AAQpE,MAAM,MAAM,yBAAyB,GAAG,CACtC,KAAK,EAAE,UAAU,KACd,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,MAAM,MAAM,yBAAyB,GAAG;IACtC,4FAA4F;IAC5F,GAAG,EAAE,MAAM,CAAC;IACZ,gGAAgG;IAChG,MAAM,EAAE,yBAAyB,CAAC;IAClC,iGAAiG;IACjG,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAUF,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAchF;AAYD;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,IAAI,EAAE;IACtD,MAAM,CAAC,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC1C,QAAQ,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9C,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA4D9B;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAK1F"}

package/dist/cjs/coverage-attestation.js

@@ -0,0 +1,146 @@
+/**
+ * cr.coverage.attest.v1 issuance (guard side).
+ *
+ * Wire/signing input MIRRORS app src/verdict-core/coverage-attestation.js. The guard SIGNS via a
+ * host-provided sign(bytes) callback — never a raw key in config. CodeRifts never holds the
+ * coverage private key. Custody model copied from tryIssueMonitoringAttestation, deliberately:
+ * one custody story for every host-signed artifact, not a second one per envelope.
+ *
+ * Observation-side only. Signer throw/empty → omit the token; never unsigned.
+ *
+ * ── THE PAYLOAD DECISION, and it is the point of this module ────────────────────────────────
+ * A signed statement must not assert more than the guard measured.
+ *
+ * The guard's own class vocabulary is WIDER than the envelope's, deliberately:
+ *   guard    UNKNOWN_OUTSIDE_SCOPE | INCOMPLETE_OBSERVED | COMPLETE_OBSERVED
+ *   envelope UNKNOWN_OUTSIDE_SCOPE | INCOMPLETE_OBSERVED          (no COMPLETE, by design)
+ *
+ * Half B absent (host never reported total dispatches): the guard knows governed_calls and
+ * nothing else. The token carries UNKNOWN_OUTSIDE_SCOPE and OMITS total_calls entirely. It does
+ * not default the total to governed_calls, and it does not send zero — absence is not zero, and a
+ * signed zero would be a lie with a signature on it.
+ *
+ * Guard COMPLETE_OBSERVED maps to envelope INCOMPLETE_OBSERVED. Not a downgrade for its own sake:
+ * the envelope's two classes encode "totals known" vs "totals unknown", and the app kernel rejects
+ * a COMPLETE payload as malformed rather than coercing it, because from inside the process the
+ * ABSENCE of an ungoverned call is unprovable. The numbers carry the finding — an empty
+ * ungoverned_tools tells the reader everything the host reported was governed, without a signed
+ * claim of completeness that we cannot back.
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COVERAGE_ATTEST_ENVELOPE_TAG = exports.COVERAGE_ATTEST_SIGNING_PREFIX = exports.COVERAGE_ATTEST_VERSION = void 0;
+exports.coverageAttestSigningInput = coverageAttestSigningInput;
+exports.tryIssueCoverageAttestation = tryIssueCoverageAttestation;
+exports.kidFromCoverageAttestation = kidFromCoverageAttestation;
+exports.COVERAGE_ATTEST_VERSION = 'cr.coverage.attest.v1';
+exports.COVERAGE_ATTEST_SIGNING_PREFIX = 'crcovattest.v1';
+exports.COVERAGE_ATTEST_ENVELOPE_TAG = 'cr.coverage.attest.v1';
+/** Envelope classes. Intentionally two — there is no COMPLETE to emit. */
+const ENVELOPE_CLASSES = ['INCOMPLETE_OBSERVED', 'UNKNOWN_OUTSIDE_SCOPE'];
+/** NUL joins the tool-name list inside one pipe field, so a name can never forge a field. */
+const NUL = '\x1f';
+function scalar(v) {
+    return v == null ? '' : String(v);
+}
+function canonicalUngoverned(list) {
+    return Array.isArray(list) ? list.map((s) => String(s)).join(NUL) : '';
+}
+function coverageAttestSigningInput(body) {
+    const parts = [
+        exports.COVERAGE_ATTEST_SIGNING_PREFIX,
+        scalar(body.kid),
+        scalar(body.session_id),
+        scalar(body.observed_class),
+        body.governed_calls != null ? String(body.governed_calls) : '',
+        body.total_calls != null ? String(body.total_calls) : '',
+        canonicalUngoverned(body.ungoverned_tools),
+        scalar(body.decision_id),
+        scalar(body.receipt_digest),
+        scalar(body.observed_at),
+    ];
+    return parts.join('|');
+}
+function b64url(buf) {
+    return buf.toString('base64url');
+}
+/** True when the host reported Half B (total dispatches), so a total may be asserted. */
+function hasHalfB(cov) {
+    return cov.class !== 'UNKNOWN_OUTSIDE_SCOPE'
+        && typeof cov.total_calls === 'number';
+}
+/**
+ * Issue a cr.coverage.attest.v1 token from a coverage snapshot. Returns undefined when config is
+ * absent, the snapshot is unusable, or the host signer throws — never an unsigned token.
+ */
+async function tryIssueCoverageAttestation(args) {
+    const cfg = args.config;
+    if (!cfg || typeof cfg.kid !== 'string' || !cfg.kid || typeof cfg.signer !== 'function') {
+        return undefined;
+    }
+    if (typeof cfg.sessionId !== 'string' || cfg.sessionId.length === 0)
+        return undefined;
+    const cov = args.coverage;
+    if (!cov || typeof cov !== 'object')
+        return undefined;
+    if (typeof cov.governed_calls !== 'number' || !Number.isInteger(cov.governed_calls) || cov.governed_calls < 0) {
+        return undefined;
+    }
+    const halfB = hasHalfB(cov);
+    const observed_class = halfB ? 'INCOMPLETE_OBSERVED' : 'UNKNOWN_OUTSIDE_SCOPE';
+    if (!ENVELOPE_CLASSES.includes(observed_class))
+        return undefined;
+    const body = {
+        v: exports.COVERAGE_ATTEST_VERSION,
+        kid: cfg.kid,
+        session_id: cfg.sessionId,
+        observed_class,
+        governed_calls: cov.governed_calls,
+        observed_at: args.now || new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    };
+    if (halfB) {
+        const withTotals = cov;
+        // A statement claiming more governed than dispatched is not a coverage statement — the app
+        // kernel rejects it as malformed, so refuse to mint it rather than emit a token that fails.
+        if (!Number.isInteger(withTotals.total_calls) || withTotals.total_calls < cov.governed_calls) {
+            return undefined;
+        }
+        body.total_calls = withTotals.total_calls;
+        body.ungoverned_tools = Array.isArray(withTotals.ungoverned_tools)
+            ? withTotals.ungoverned_tools.map((s) => String(s))
+            : [];
+    }
+    // else: total_calls and ungoverned_tools are OMITTED. Not zero. Not defaulted.
+    if (typeof args.decisionId === 'string' && args.decisionId)
+        body.decision_id = args.decisionId;
+    if (typeof args.receiptDigest === 'string' && args.receiptDigest)
+        body.receipt_digest = args.receiptDigest;
+    const input = Buffer.from(coverageAttestSigningInput(body), 'utf8');
+    let sig;
+    try {
+        sig = await cfg.signer(input);
+    }
+    catch {
+        return undefined;
+    }
+    if (sig == null)
+        return undefined;
+    const sigBuf = Buffer.isBuffer(sig) ? sig : Buffer.from(sig);
+    if (sigBuf.length === 0)
+        return undefined;
+    return [
+        exports.COVERAGE_ATTEST_ENVELOPE_TAG,
+        cfg.kid,
+        b64url(Buffer.from(JSON.stringify(body), 'utf8')),
+        b64url(sigBuf),
+    ].join('|');
+}
+function kidFromCoverageAttestation(token) {
+    if (typeof token !== 'string' || token.length === 0)
+        return null;
+    const parts = token.split('|');
+    if (parts.length !== 4 || parts[0] !== exports.COVERAGE_ATTEST_ENVELOPE_TAG)
+        return null;
+    return parts[1] || null;
+}
+//# sourceMappingURL=coverage-attestation.js.map

package/dist/cjs/coverage-attestation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-attestation.js","sourceRoot":"","sources":["../../src/coverage-attestation.ts"],"names":[],"mappings":"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"}

package/dist/cjs/execution-grant.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Native execution-grant helpers (9.6.0).
+ *
+ * Grant request is per guardToolCall invocation (local vars). The token is not
+ * a verdict input and is not folded into any fingerprint preimage.
+ */
+export type ExecutionGrantConfig = {
+    enabled: true;
+    resolveStateNonce?: (ctx: {
+        artifactId: string | null;
+        toolName: string;
+        args: unknown;
+    }) => string | Promise<string>;
+};
+export type ExecutionGrantObservation = {
+    requested: boolean;
+    arrived: boolean;
+};
+export type ExecutionGrantCallContext = {
+    execution_grant: string | null;
+};
+export declare function isExecutionGrantEnabled(config: {
+    executionGrant?: ExecutionGrantConfig;
+} | null | undefined): boolean;
+export declare function readExecutionGrantToken(response: unknown): string | null;
+export declare function firstArtifactId(artifacts: unknown): string | null;
+/** True when the thrown authorize error carries the named SIGNER_UNAVAILABLE code. */
+export declare function isSignerUnavailableError(err: unknown): boolean;
+export declare function resolveStateNonceForCall(config: {
+    executionGrant?: ExecutionGrantConfig;
+}, call: {
+    toolName: string;
+    arguments?: unknown;
+    artifacts?: unknown;
+}, artifacts: unknown): Promise<{
+    ok: true;
+    nonce?: string;
+} | {
+    ok: false;
+}>;
+//# sourceMappingURL=execution-grant.d.ts.map

package/dist/cjs/execution-grant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-grant.d.ts","sourceRoot":"","sources":["../../src/execution-grant.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,IAAI,CAAC;IACd,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE;QACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,OAAO,CAAC;KACf,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAAE,cAAc,CAAC,EAAE,oBAAoB,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAErH;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAIxE;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CASjE;AAED,sFAAsF;AACtF,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAM9D;AAED,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE;IAAE,cAAc,CAAC,EAAE,oBAAoB,CAAA;CAAE,EACjD,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,EACpE,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAevD"}

package/dist/cjs/execution-grant.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Native execution-grant helpers (9.6.0).
+ *
+ * Grant request is per guardToolCall invocation (local vars). The token is not
+ * a verdict input and is not folded into any fingerprint preimage.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isExecutionGrantEnabled = isExecutionGrantEnabled;
+exports.readExecutionGrantToken = readExecutionGrantToken;
+exports.firstArtifactId = firstArtifactId;
+exports.isSignerUnavailableError = isSignerUnavailableError;
+exports.resolveStateNonceForCall = resolveStateNonceForCall;
+function isExecutionGrantEnabled(config) {
+    return !!(config && config.executionGrant && config.executionGrant.enabled === true);
+}
+function readExecutionGrantToken(response) {
+    if (!response || typeof response !== 'object')
+        return null;
+    const g = response.execution_grant;
+    return typeof g === 'string' && g.length > 0 ? g : null;
+}
+function firstArtifactId(artifacts) {
+    if (!Array.isArray(artifacts))
+        return null;
+    for (const a of artifacts) {
+        if (a && typeof a === 'object' && typeof a.id === 'string') {
+            const id = String(a.id).trim();
+            if (id)
+                return id;
+        }
+    }
+    return null;
+}
+/** True when the thrown authorize error carries the named SIGNER_UNAVAILABLE code. */
+function isSignerUnavailableError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    if (e.code === 'SIGNER_UNAVAILABLE')
+        return true;
+    if (e.body && e.body.code === 'SIGNER_UNAVAILABLE')
+        return true;
+    return false;
+}
+async function resolveStateNonceForCall(config, call, artifacts) {
+    const resolver = config.executionGrant && config.executionGrant.resolveStateNonce;
+    if (typeof resolver !== 'function')
+        return { ok: true };
+    try {
+        const raw = await resolver({
+            artifactId: firstArtifactId(artifacts) || firstArtifactId(call.artifacts),
+            toolName: call.toolName,
+            args: call.arguments,
+        });
+        if (raw == null || raw === '')
+            return { ok: true };
+        if (typeof raw !== 'string')
+            return { ok: false };
+        return { ok: true, nonce: raw };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+//# sourceMappingURL=execution-grant.js.map

package/dist/cjs/execution-grant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-grant.js","sourceRoot":"","sources":["../../src/execution-grant.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAoBH,0DAEC;AAED,0DAIC;AAED,0CASC;AAGD,4DAMC;AAED,4DAmBC;AAjDD,SAAgB,uBAAuB,CAAC,MAAoE;IAC1G,OAAO,CAAC,CAAC,CAAC,MAAM,IAAI,MAAM,CAAC,cAAc,IAAI,MAAM,CAAC,cAAc,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC;AACvF,CAAC;AAED,SAAgB,uBAAuB,CAAC,QAAiB;IACvD,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3D,MAAM,CAAC,GAAI,QAA0C,CAAC,eAAe,CAAC;IACtE,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1D,CAAC;AAED,SAAgB,eAAe,CAAC,SAAkB;IAChD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAQ,CAAsB,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;YACjF,MAAM,EAAE,GAAG,MAAM,CAAE,CAAoB,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YACnD,IAAI,EAAE;gBAAE,OAAO,EAAE,CAAC;QACpB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,sFAAsF;AACtF,SAAgB,wBAAwB,CAAC,GAAY;IACnD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClD,MAAM,CAAC,GAAG,GAAoD,CAAC;IAC/D,IAAI,CAAC,CAAC,IAAI,KAAK,oBAAoB;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,oBAAoB;QAAE,OAAO,IAAI,CAAC;IAChE,OAAO,KAAK,CAAC;AACf,CAAC;AAEM,KAAK,UAAU,wBAAwB,CAC5C,MAAiD,EACjD,IAAoE,EACpE,SAAkB;IAElB,MAAM,QAAQ,GAAG,MAAM,CAAC,cAAc,IAAI,MAAM,CAAC,cAAc,CAAC,iBAAiB,CAAC;IAClF,IAAI,OAAO,QAAQ,KAAK,UAAU;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACxD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC;YACzB,UAAU,EAAE,eAAe,CAAC,SAAS,CAAC,IAAI,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC;YACzE,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,IAAI,EAAE,IAAI,CAAC,SAAS;SACrB,CAAC,CAAC;QACH,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,KAAK,EAAE;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;QACnD,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;QAClD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/cjs/guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,WAAW,EAAE,YAAY,EACT,kBAAkB,EAAE,cAAc,EAEnD,MAAM,YAAY,CAAC;AAYpB,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAGL,KAAK,2BAA2B,EACjC,MAAM,wBAAwB,CAAC;AA+ZhC;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,kBAAkB,EACxB,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,EACjC,MAAM,EAAE,WAAW,EACnB,WAAW,CAAC,EAAE,oBAAoB,GAAG,2BAA2B,GAC/D,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CA+Y1B"}
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,WAAW,EAAE,YAAY,EACT,kBAAkB,EAAE,cAAc,EAEnD,MAAM,YAAY,CAAC;AAYpB,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAGL,KAAK,2BAA2B,EACjC,MAAM,wBAAwB,CAAC;AAgchC;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,kBAAkB,EACxB,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,EACjC,MAAM,EAAE,WAAW,EACnB,WAAW,CAAC,EAAE,oBAAoB,GAAG,2BAA2B,GAC/D,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAqc1B"}