@vess-id/ai-identity 0.0.0-dev-20260902121045

package/dist/internal-signature/canonical.d.ts

@@ -0,0 +1,80 @@
+/**
+ * P1-A14a-1 / Threat Model S4 — canonical-string + signature-header
+ * helpers for HMAC body signing of internal HTTP requests.
+ *
+ * Pure module: no NestJS, no I/O, no side effects. SDK is the
+ * single source of truth (P1-A14a-2d) — api / remote-mcp /
+ * slack-bot all import from `@vess-id/ai-identity`.
+ *
+ * Header format (Q1 = A, Stripe-style versioned):
+ *   X-Internal-Signature: v1=<keyId>:<unixSeconds>:<base64(hmac)>
+ *
+ * Canonical string (Q2 = A, no header inclusion):
+ *   ${METHOD.toUpperCase()}\n${path}\n${unixSeconds}\n${sha256Hex(rawBody)}
+ *
+ * Replay window (Q3 = A): 300 seconds — enforced by the api guard,
+ * not here. This module is responsible for *constructing* the
+ * canonical string and *parsing* the header; freshness is policy.
+ */
+export declare const SIGNATURE_HEADER = "x-internal-signature";
+export declare const SIGNATURE_VERSION_PREFIX = "v1=";
+/**
+ * SHA-256 hex digest of an arbitrary buffer or string. Hex (not
+ * base64) so the canonical string is URL-safe and grep-friendly in
+ * logs if a future debug session ever needs to reconstruct it
+ * server-side.
+ */
+export declare function sha256Hex(input: Buffer | string): string;
+/**
+ * Build the canonical string that gets HMAC'd. The components are
+ * separated by `\n` because no legitimate input contains `\n` (the
+ * method is uppercase ASCII, the path is URL-encoded by the caller,
+ * the timestamp is digits, the body hash is hex). Using `\n` as
+ * separator avoids ambiguity that delimiters like `:` would
+ * introduce when the path contains a colon.
+ *
+ * Whitespace is NOT trimmed — input must be exactly what will land
+ * on the wire. Caller controls case and encoding.
+ */
+export declare function buildCanonicalString(args: {
+    method: string;
+    path: string;
+    unixSeconds: number;
+    rawBody: Buffer | string;
+}): string;
+/** Shape of a parsed `X-Internal-Signature` header. */
+export interface ParsedSignature {
+    /** Identifier of the signing key (e.g. `'mcp-v2'`). */
+    keyId: string;
+    /** Unix epoch seconds at signing time. */
+    unixSeconds: number;
+    /** Base64-encoded HMAC-SHA256 digest. */
+    signature: string;
+}
+/**
+ * Parse a `X-Internal-Signature` header value. Returns `null` for
+ * any malformed shape rather than throwing — the api guard converts
+ * `null` to a `401 Unauthorized` so a malformed header never
+ * triggers a `500`.
+ *
+ * Accepted: `v1=<keyId>:<digits>:<base64>`
+ *
+ * Defensive checks:
+ *   - Must start with `v1=` (Q1: explicit version prefix)
+ *   - keyId / signature must be non-empty after split
+ *   - timestamp must parse to a finite, non-negative integer
+ *   - keyId must be ASCII identifier-safe ([A-Za-z0-9_-]+) so a
+ *     malicious header cannot smuggle control chars or whitespace
+ *     into log lines / metric labels
+ *   - signature must be valid base64 (only base64 alphabet chars)
+ */
+export declare function parseSignatureHeader(headerValue: string | undefined): ParsedSignature | null;
+/**
+ * Format a ParsedSignature back into a header string. Round-trips
+ * with `parseSignatureHeader` for any validly-shaped input.
+ *
+ * Used by the signing side (HTTP client). Keeping it next to the
+ * parser pins the format in one place.
+ */
+export declare function formatSignatureHeader(parsed: ParsedSignature): string;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/internal-signature/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../src/internal-signature/canonical.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAO,MAAM,gBAAgB,yBAAyB,CAAA;AACtD,eAAO,MAAM,wBAAwB,QAAQ,CAAA;AAE7C;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;CACzB,GAAG,MAAM,CAGT;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAA;IACb,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAA;IACnB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,IAAI,CA4B5F;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAErE"}

package/dist/internal-signature/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Public API of `@vess-id/ai-identity/internal-signature` (P1-A14a-2d).
+ *
+ * Re-exported via the SDK barrel (`packages/sdk/src/index.ts`) so
+ * consumers can write:
+ *
+ *   import { signRequest, SIGNATURE_HEADER } from '@vess-id/ai-identity'
+ *
+ * SDK is the single source of truth — api / remote-mcp / slack-bot
+ * all import from here. The api side keeps verifier-only types
+ * (`HmacKeyset`, `InternalSignatureGuard`) in
+ * `packages/api/src/common/internal-signature/` so the SDK avoids
+ * a NestJS dependency.
+ */
+export { buildCanonicalString, formatSignatureHeader, parseSignatureHeader, sha256Hex, SIGNATURE_HEADER, SIGNATURE_VERSION_PREFIX, type ParsedSignature, } from './canonical';
+export { signRequest, MIN_SIGNER_KEY_BYTES, type InternalHmacSignerKey, type SignRequestArgs, } from './signer';
+//# sourceMappingURL=index.d.ts.map

package/dist/internal-signature/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/internal-signature/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,SAAS,EACT,gBAAgB,EAChB,wBAAwB,EACxB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,GACrB,MAAM,UAAU,CAAA"}

package/dist/internal-signature/signer.d.ts

@@ -0,0 +1,76 @@
+/**
+ * P1-A14a-2d — pure HMAC signer for outbound /api/internal/**
+ * requests. Lives in SDK so remote-mcp and slack-bot (both of which
+ * already depend on `@vess-id/ai-identity`) can attach
+ * `X-Internal-Signature` to every request without dragging the
+ * api package into their dependency graph.
+ *
+ * Pure (no I/O, no Nest). Mirrors the `utils/crypto.ts` profile:
+ * the only Node-builtin used is `crypto.createHmac`.
+ *
+ * Pairing with the verifier
+ * -------------------------
+ * The verifier (api side, `HmacKeyset.verify` →
+ * `buildCanonicalString` → constant-time compare) reads the same
+ * `buildCanonicalString` from this module by construction. As long
+ * as both sides pass the same `(method, path, unixSeconds, rawBody)`
+ * the HMACs match by definition.
+ *
+ * Body bytes
+ * ----------
+ * The caller MUST pass the exact bytes that go on the wire as
+ * `rawBody`. Re-running `JSON.stringify(...)` on each side would
+ * risk a byte mismatch (object key order is implementation-defined
+ * in spec, even though V8 preserves insertion order in practice).
+ * The api-client `makeRequest` helper computes `JSON.stringify`
+ * once, hands the same string to both `signRequest` and `fetch`.
+ */
+/**
+ * Minimum signer key length in raw bytes. 32 bytes = 256 bits
+ * matches HMAC-SHA256's natural block size and the verifier's
+ * `MIN_KEY_BYTES`. A truncated env var (accidental newline,
+ * copy-paste error) is the realistic failure mode this guards
+ * against.
+ */
+export declare const MIN_SIGNER_KEY_BYTES = 32;
+export interface InternalHmacSignerKey {
+    /** Stable identifier for the key, e.g. `'mcp-v1'`. Embedded in
+     *  the X-Internal-Signature header so the verifier can pick the
+     *  right key. Must match `/^[A-Za-z0-9_-]+$/`. */
+    keyId: string;
+    /** Raw HMAC secret. >= MIN_SIGNER_KEY_BYTES bytes. */
+    secret: Buffer;
+}
+export interface SignRequestArgs {
+    /** HTTP method. Will be upper-cased by `buildCanonicalString`,
+     *  but callers should pass the uppercase form they use on the
+     *  wire so signer and `fetch()` stay in lockstep. */
+    method: string;
+    /** URL path with query string already stripped (verifier does
+     *  `request.originalUrl?.split('?')[0]`; signer must mirror).
+     *  Path encoding (e.g. `%2F` vs `/`) is caller's responsibility
+     *  — the canonical string treats them as different bytes. */
+    path: string;
+    /** Wire bytes. The same string/buffer passed to `fetch({body})`
+     *  must be passed here — `JSON.stringify` runs ONCE per request
+     *  in the caller. */
+    rawBody: Buffer | string;
+    /** Optional fixed timestamp for testing. Defaults to
+     *  `Math.floor(Date.now() / 1000)`. */
+    unixSeconds?: number;
+}
+/**
+ * Sign an outbound request and return a fully-formatted
+ * `X-Internal-Signature` header value. The caller sets the header
+ * on the outbound request directly:
+ *
+ * ```ts
+ * headers[SIGNATURE_HEADER] = signRequest(key, { method, path, rawBody })
+ * ```
+ *
+ * Throws if key material is invalid (bad keyId or short secret) —
+ * surfacing misconfiguration loudly at request time rather than
+ * silently producing a header the verifier will reject.
+ */
+export declare function signRequest(key: InternalHmacSignerKey, args: SignRequestArgs): string;
+//# sourceMappingURL=signer.d.ts.map

package/dist/internal-signature/signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../../src/internal-signature/signer.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC,MAAM,WAAW,qBAAqB;IACpC;;sDAEkD;IAClD,KAAK,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,eAAe;IAC9B;;yDAEqD;IACrD,MAAM,EAAE,MAAM,CAAA;IACd;;;iEAG6D;IAC7D,IAAI,EAAE,MAAM,CAAA;IACZ;;yBAEqB;IACrB,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;IACxB;2CACuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,qBAAqB,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,CAgBrF"}

package/dist/policy/cedar-engine.d.ts

@@ -0,0 +1,334 @@
+/**
+ * CedarEngine — minimal wrapper around `@cedar-policy/cedar-wasm/nodejs`.
+ *
+ * Phase 1 Step 1 scope (server-side / Node-runtime only):
+ *   - preparseSchema   : ingest Cedar schema text → opaque SchemaHandle
+ *   - preparsePolicySet: ingest Cedar PolicySet text → opaque PolicySetHandle
+ *   - evaluate         : run statefulIsAuthorized against preparsed handles
+ *
+ * Browser callers receive `CedarEngineUnavailableError` because the
+ * `/nodejs` subpath depends on Node `fs` to instantiate the wasm.
+ *
+ * Performance notes (companion design spec Appendix C, PoC 2026-05-23):
+ *   - statefulIsAuthorized + preparsed cache: p50 0.067ms / p99 0.076ms
+ *     (~9x faster than re-parsing every call). The wasm caches preparsed
+ *     handles internally keyed by string name/id, so the opaque handles
+ *     we expose are thin wrappers around an auto-generated id.
+ *
+ * Concurrency / TOCTOU (Cedar design spec rev 5/6, fix C3):
+ *   - `createCedarEngine()` caches the in-flight Promise (not the resolved
+ *     engine). Two parallel callers therefore share the same load — no
+ *     duplicated dynamic import of the 4.1 MB wasm.
+ *   - On load failure the cached promise is cleared so the next caller can
+ *     retry. This avoids permanently poisoning the module after a transient
+ *     failure (e.g. wasm streaming compile blip).
+ *
+ * Design ref: docs/specs/2026-05-23-cedar-rar-permission-redesign.md
+ * Plan ref:   docs/specs/2026-05-23-cedar-rar-implementation-plan-phase1.md
+ */
+/**
+ * Decision domain exposed by the wrapper. Cedar's wasm uses lowercase
+ * `'allow' | 'deny'`; we normalize to the spec's casing so callers can
+ * pattern-match on a single canonical form across the codebase.
+ */
+export type CedarDecision = 'Allow' | 'Deny';
+/**
+ * Structured error returned for evaluation-time problems (policy execution
+ * errors). Parse / schema errors are surfaced at preparse time as thrown
+ * `CedarParseError`s instead.
+ */
+export interface CedarError {
+    /** Policy id that errored, if attributable. */
+    policyId?: string;
+    /** Human-readable message from Cedar. */
+    message: string;
+    /** Optional structured diagnostic code from Cedar. */
+    code?: string;
+}
+/**
+ * Phase 2-1-H — structured policy validation error surfaced by
+ * `CedarParseError.validationErrors` (and re-exported as a public type
+ * so API / UI callers don't have to re-implement source-location math).
+ *
+ * One `PolicyValidationError` entry corresponds to one cedar-wasm
+ * diagnostic (top-level `errors[]` entries + their `related[]`
+ * descendants are flattened into a single list, since callers always
+ * want to render every diagnostic — the related chain is metadata about
+ * the top-level failure, not a separate parse).
+ *
+ * Fields:
+ *   - `code` — machine-readable classification, snake_case. Phase 1
+ *     surface: `'parse_error'` (default). Future cedar-wasm releases
+ *     ship structured codes; the classifier here uses message-pattern
+ *     heuristics until then (see `classifyCedarErrorMessage`).
+ *   - `message` — cedar-wasm's human-readable English. UI is
+ *     responsible for i18n / templating; we don't translate here.
+ *   - `line` / `column` — 1-based caret. Computed from the byte
+ *     `start` offset in cedar-wasm's `sourceLocations[]` against the
+ *     ORIGINAL policy text, so the caret matches what the user sees
+ *     in the textarea / editor.
+ *   - `context` — the offending byte slice (max 200 chars, truncated
+ *     with an ellipsis). Lets UIs render an inline highlight without
+ *     a second round trip.
+ *   - `offset` — 0-based byte offset (for editors that prefer offsets
+ *     to line/column; line/column is provided as a convenience).
+ */
+export interface PolicyValidationError {
+    /**
+     * Machine-readable code, snake_case. Currently a small set:
+     *   - `'parse_error'` — syntax / grammar failure (default)
+     *   - `'unexpected_end_of_input'` — incomplete policy
+     *   - `'unexpected_token'` — token didn't match expected production
+     *   - `'unknown_extension'` — referenced an unknown extension fn
+     *   - `'unknown'` — fallback when no heuristic matches
+     * Callers that switch on this string MUST default to a generic
+     * branch — the set will grow as cedar-wasm exposes structured codes.
+     */
+    code: string;
+    /** Cedar's human-readable English diagnostic. */
+    message: string;
+    /** 1-based line in the original policy text where the error starts. */
+    line?: number;
+    /** 1-based column in the line (counts UTF-16 code units, matching JS String). */
+    column?: number;
+    /**
+     * The raw policy slice that triggered the error, truncated to 200
+     * chars with a trailing ellipsis when longer. Useful for UIs to
+     * highlight the offending span without re-computing offsets.
+     */
+    context?: string;
+    /** 0-based byte offset into the policy text (when known). */
+    offset?: number;
+}
+/**
+ * Opaque handle to a Cedar schema that has been parsed and cached
+ * inside the wasm. Returned by `preparseSchema`; pass to `evaluate`.
+ *
+ * The wasm caches by string name, so the handle carries the auto-generated
+ * id. Callers must treat the type as opaque.
+ */
+export interface SchemaHandle {
+    readonly __cedar: 'schema';
+    readonly name: string;
+}
+/** Opaque handle to a Cedar PolicySet. Returned by `preparsePolicySet`. */
+export interface PolicySetHandle {
+    readonly __cedar: 'policySet';
+    readonly id: string;
+}
+/**
+ * A Cedar entity in the JSON shape expected by the wasm.
+ *
+ * We keep this as `Record<string, unknown>` rather than importing the
+ * detailed `EntityJson` type from `@cedar-policy/cedar-wasm` because the
+ * SDK is consumed by browser bundlers; pulling in the d.ts would force
+ * the wasm typings into browser builds (the runtime is still lazy-loaded).
+ * Callers cast as needed; runtime validation is delegated to the wasm.
+ */
+export type CedarEntity = Record<string, unknown>;
+export interface CedarEvaluateRequest {
+    /** Cedar entity-uid expression, e.g. `Agent::"agent-1"`. */
+    principal: string;
+    /** Cedar entity-uid expression, e.g. `Action::"gmail.message.send"`. */
+    action: string;
+    /** Cedar entity-uid expression, e.g. `GmailThread::"thread-1"`. */
+    resource: string;
+    /** Free-form context dict (must match the schema's context shape). */
+    context: Record<string, unknown>;
+}
+export interface EvaluateInput {
+    policySetHandle: PolicySetHandle;
+    schemaHandle?: SchemaHandle;
+    entities: ReadonlyArray<CedarEntity>;
+    request: CedarEvaluateRequest;
+}
+export interface EvaluateResult {
+    decision: CedarDecision;
+    /** Policy ids that determined the decision (Cedar's `diagnostics.reason`). */
+    reasons: string[];
+    /** Evaluation-time errors, if any. Empty array on success. */
+    errors: CedarError[];
+}
+export interface CedarEngine {
+    preparseSchema(schemaText: string): SchemaHandle;
+    preparsePolicySet(cedarText: string): PolicySetHandle;
+    evaluate(input: EvaluateInput): EvaluateResult;
+}
+/**
+ * Thrown when the Cedar wasm module cannot be loaded — typically because
+ * the wrapper is running in a browser (the `/nodejs` subpath requires Node
+ * `fs`), but also raised for any unexpected load-time failure.
+ */
+export declare class CedarEngineUnavailableError extends Error {
+    readonly name = "CedarEngineUnavailableError";
+    constructor(cause: unknown);
+}
+/**
+ * Thrown by `preparseSchema` / `preparsePolicySet` when Cedar reports a
+ * structured `{ type: 'failure', errors: [...] }` answer. Callers (e.g.
+ * the Policy Registry lint) can inspect `errors` for diagnostics.
+ *
+ * Phase 2-1-H — `validationErrors` is a parallel, richer view of the
+ * same failures with line / column / context derived against the
+ * original policy text. The legacy `errors` field is preserved as-is
+ * so call sites that only need the message text don't need to change.
+ */
+export declare class CedarParseError extends Error {
+    readonly name = "CedarParseError";
+    readonly errors: CedarError[];
+    /**
+     * Structured diagnostics with `{ code, message, line, column, context,
+     * offset }`. Always non-empty when the throw is from cedar-wasm; may
+     * be empty when constructed from a non-cedar-wasm path (e.g. when an
+     * upstream caller wraps an unexpected throw).
+     */
+    readonly validationErrors: PolicyValidationError[];
+    constructor(message: string, errors: CedarError[], validationErrors?: PolicyValidationError[]);
+}
+/**
+ * Minimal subset of the cedar-wasm module surface we depend on. We type only
+ * the shape we use so the SDK's d.ts doesn't accidentally pull in the full
+ * upstream typings (which would broaden the public type-surface).
+ */
+interface CedarWasmModule {
+    preparseSchema(name: string, schema: string): CedarCheckParseAnswer;
+    preparsePolicySet(psetId: string, policies: {
+        staticPolicies: string;
+    }): CedarCheckParseAnswer;
+    statefulIsAuthorized(call: CedarStatefulCall): CedarAuthorizationAnswer;
+}
+interface CedarStatefulCall {
+    principal: {
+        type: string;
+        id: string;
+    };
+    action: {
+        type: string;
+        id: string;
+    };
+    resource: {
+        type: string;
+        id: string;
+    };
+    context: Record<string, unknown>;
+    preparsedSchemaName?: string;
+    preparsedPolicySetId: string;
+    validateRequest?: boolean;
+    entities: ReadonlyArray<CedarEntity>;
+}
+type CedarCheckParseAnswer = {
+    type: 'success';
+} | {
+    type: 'failure';
+    errors: CedarDetailedError[];
+};
+type CedarAuthorizationAnswer = {
+    type: 'success';
+    response: {
+        decision: 'allow' | 'deny';
+        diagnostics: {
+            reason: string[];
+            errors: CedarAuthorizationError[];
+        };
+    };
+    warnings: CedarDetailedError[];
+} | {
+    type: 'failure';
+    errors: CedarDetailedError[];
+    warnings: CedarDetailedError[];
+};
+interface CedarDetailedError {
+    message: string;
+    code?: string | null;
+    /**
+     * Source spans reported by cedar-wasm's miette-backed diagnostic
+     * pipeline. `start` / `end` are 0-based byte offsets into the policy
+     * text. `label` is a short hint about what was expected. We type only
+     * the subset we use; cedar-wasm may include additional fields.
+     */
+    sourceLocations?: ReadonlyArray<{
+        start?: number;
+        end?: number;
+        label?: string | null;
+    }> | null;
+    /** Cascaded diagnostics — same shape as the top-level error. */
+    related?: ReadonlyArray<CedarDetailedError> | null;
+}
+interface CedarAuthorizationError {
+    policyId: string;
+    error: CedarDetailedError;
+}
+type CedarLoader = () => Promise<CedarWasmModule>;
+/**
+ * Create (or reuse) the singleton Cedar engine.
+ *
+ * - First call performs the dynamic import of cedar-wasm.
+ * - Subsequent calls return the cached Promise — TOCTOU-safe.
+ * - If the in-flight load rejects, the cache is cleared so retries work.
+ */
+export declare function createCedarEngine(): Promise<CedarEngine>;
+/**
+ * Phase 2-1-H — flatten cedar-wasm's `{ message, sourceLocations[],
+ * related[] }` tree into a list of `PolicyValidationError` entries
+ * with line/column derived against the original policy text.
+ *
+ * `related[]` entries are walked recursively and emitted as siblings
+ * of the top-level error (cedar-wasm uses `related` for "and also..."
+ * style cascade diagnostics — UIs typically render all of them, not
+ * just the head).
+ *
+ * If cedar-wasm returns no `sourceLocations`, we still emit an entry
+ * (without line/column) so the caller always sees at least one error
+ * per failure path.
+ *
+ * @internal — Phase 2-1-H heuristic implementation. Exported for cross-package
+ * reuse (API + agentd / remote-mcp future surfaces) and unit tests, but NOT a
+ * stable public API. Will be replaced once cedar-wasm exposes structured
+ * diagnostic codes upstream (tracked as Phase 2-2-I). Semver of `@vess-id/ai-identity`
+ * may remove or rename this function without a major bump.
+ */
+export declare function buildValidationErrors(errors: ReadonlyArray<CedarDetailedError>, sourceText: string): PolicyValidationError[];
+/**
+ * Heuristic classifier mapping cedar-wasm's English message text to a
+ * stable snake_case code. cedar-wasm@4.11.0 does not yet expose a
+ * structured `code` field (the `code` slot in `CedarDetailedError` is
+ * always `null` for parse failures), so we match on substring patterns
+ * that have proven stable across recent releases.
+ *
+ * If `cedarCode` is supplied (future cedar-wasm release) it wins.
+ *
+ * Returned codes (must stay in sync with the JSDoc on
+ * `PolicyValidationError.code`):
+ *   - `parse_error`              — generic parse failure (fallback)
+ *   - `unexpected_end_of_input`  — incomplete policy
+ *   - `unexpected_token`         — token didn't match expected production
+ *   - `unknown_extension`        — referenced unknown extension fn
+ *   - `unknown`                  — message didn't match any pattern
+ *
+ * @internal — Phase 2-1-H heuristic implementation, same caveat as
+ * `buildValidationErrors`. Will be replaced once cedar-wasm exposes structured
+ * diagnostic codes upstream (Phase 2-2-I).
+ */
+export declare function classifyCedarErrorMessage(message: string, cedarCode?: string): string;
+/** Drop the cached engine Promise. Production callers should never need this. */
+export declare function __resetCedarEngineCache(): void;
+/**
+ * Override the cedar-wasm loader used by `createCedarEngine`. Pass `null` to
+ * restore the default dynamic-import loader.
+ */
+export declare function __setCedarLoaderForTests(loader: CedarLoader | null): void;
+/**
+ * Test-only wrapper around the module-internal `parseEntityUid`. Lets the
+ * spec assert the entity-uid regex directly (e.g. that single-colon namespace
+ * forms are rejected) without contorting `evaluate` invocations.
+ *
+ * Production code MUST NOT call this — the leading underscores follow the
+ * `__resetCedarEngineCache` / `__setCedarLoaderForTests` convention used
+ * elsewhere in this module for test-only escape hatches.
+ */
+export declare function __parseEntityUidForTests(uid: string): {
+    type: string;
+    id: string;
+};
+export {};
+//# sourceMappingURL=cedar-engine.d.ts.map

package/dist/policy/cedar-engine.d.ts.map

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

package/dist/policy/cedar-entities.d.ts

@@ -0,0 +1,59 @@
+/**
+ * buildCedarEntities — Cedar entity-list builder (Cedar unification Step 1).
+ *
+ * Spec ref:
+ * - docs/specs/2026-05-24-cedar-unification-design.md §7.1
+ *   Phase 1 採用方針: entity attribute と context の **二重 bind**。本 helper は
+ *   entity 側のみを組み立て、`context.action.risk_level` は呼び出し側
+ *   (`CedarDecisionService.buildCedarEvaluateRequest`) が context にも別途
+ *   注入する。これは Cedar 4.11.0 が schema-less な entity attribute 直参照を
+ *   policy text 内では制限するため、policy 内では `context.action.risk_level`
+ *   経由を Phase 1 で採用するという rev 3 C1 で確定した設計判断による。
+ *
+ * Action entity の `attrs.risk_level` は本 helper の責務、
+ * `context.action.risk_level` は CedarDecisionService の責務。
+ * Phase 2+ で Cedar schema 導入時に context 側を撤去し entity 直参照に統一する。
+ */
+import type { CedarEntity } from './cedar-engine';
+/**
+ * Principal or resource descriptor accepted by {@link buildCedarEntities}.
+ * `type` is the Cedar entity-type name (e.g., `Agent`, `User`, `GmailThread`).
+ * `attrs` defaults to `{}` if omitted. `parents` is always `[]` in Phase 1
+ * (entity hierarchy is reserved for Phase 2 schema work).
+ */
+export interface CedarEntityDescriptor {
+    type: string;
+    id: string;
+    attrs?: Record<string, unknown>;
+}
+/**
+ * Input contract for {@link buildCedarEntities}. `action` is the dotted
+ * action name (e.g., `'gmail.message.send'`); the helper looks up the
+ * Phase 1 risk level via {@link resolveActionRisk} and binds it as
+ * `Action::"<id>".attrs.risk_level`.
+ *
+ * Context (including `context.action.risk_level`, `context.approval.granted`,
+ * `context.environment.*`) is **not** built here — the caller (typically
+ * `CedarDecisionService`) builds context separately because the same entities
+ * are reused across Phase A / Phase B (approval=false / approval=true)
+ * evaluations.
+ */
+export interface CedarEntitiesInput {
+    principal: CedarEntityDescriptor;
+    action: string;
+    resource: CedarEntityDescriptor;
+}
+/**
+ * Build the Cedar entity list (principal + action + resource) for a single
+ * authorization evaluation.
+ *
+ * Returns exactly 3 entities, in stable order [principal, action, resource].
+ * The Action entity gets `attrs.risk_level` populated from
+ * {@link resolveActionRisk}. principal / resource pass through `attrs`
+ * unchanged (defaulting to `{}` when omitted).
+ *
+ * Entity hierarchy (`parents`) is intentionally empty in Phase 1 — Phase 2
+ * will introduce schema-driven parents (e.g., GmailThread → GmailLabel).
+ */
+export declare function buildCedarEntities(input: CedarEntitiesInput): CedarEntity[];
+//# sourceMappingURL=cedar-entities.d.ts.map

package/dist/policy/cedar-entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cedar-entities.d.ts","sourceRoot":"","sources":["../../src/policy/cedar-entities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAGjD;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,qBAAqB,CAAA;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,qBAAqB,CAAA;CAChC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,WAAW,EAAE,CAsB3E"}

package/dist/policy/decision.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Decision 7-value enum — A2A / AP2 aligned (Cedar unification Step 1).
+ *
+ * Spec ref:
+ * - docs/specs/2026-05-24-cedar-unification-design.md §3
+ * - decision #9 (Locked Decisions §2): A2A 互換 7 値、後方互換破壊 OK
+ *
+ * HTTP mapping (spec §3, line 169):
+ *   - `permit`         → 200
+ *   - `auth_required`  → 202 (replaces legacy `RequireApproval`)
+ *   - `input_required` → reserved for Phase 2+
+ *   - `denied`         → 403 (explicit forbid policy match)
+ *   - `denied_default` → 403 (no permit policy matched)
+ *   - `denied_by_user` → 403 (HITL UI rejection)
+ *   - `indeterminate`  → 500 (Cedar evaluation error, fail-closed)
+ *
+ * Phase 1 Step 1 scope: SDK enum + runtime guard only.
+ * Step 2 (API layer) will rewire `CedarDecisionService` to emit these values
+ * and replace the legacy 3-value `CedarDecisionValue` (`Permit | Forbid |
+ * RequireApproval`) over the wire. Both types coexist during the transition.
+ */
+/**
+ * The 7 decision states a permission evaluator may emit. Lowercase + snake_case
+ * to match A2A protocol naming conventions.
+ */
+export type Decision = 'permit' | 'auth_required' | 'input_required' | 'denied' | 'denied_default' | 'denied_by_user' | 'indeterminate';
+/**
+ * Frozen ordered tuple of every {@link Decision} value. Useful for `it.each`
+ * test enumeration, exhaustiveness assertions, and audit-log validation.
+ *
+ * The order is **stable** and is the canonical iteration order (permit first,
+ * then approval gate, then input gate, then the 3 denied variants, then the
+ * fail-closed indeterminate). Do not rely on alphabetic order.
+ */
+export declare const DECISION_VALUES: readonly ["permit", "auth_required", "input_required", "denied", "denied_default", "denied_by_user", "indeterminate"];
+/**
+ * Runtime type guard for {@link Decision}. Returns `true` only if `value` is
+ * one of the 7 canonical literals. Use this when validating wire payloads
+ * (audit log rows, HTTP bodies, IPC) before narrowing to `Decision`.
+ *
+ * Legacy 3-value capitalized literals (`Permit`, `Forbid`, `RequireApproval`)
+ * are **not** accepted; callers that still need to handle the old wire format
+ * must do their own translation (Step 2 will provide the migration helper).
+ */
+export declare function isDecision(value: unknown): value is Decision;
+//# sourceMappingURL=decision.d.ts.map

package/dist/policy/decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../../src/policy/decision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAChB,QAAQ,GACR,eAAe,GACf,gBAAgB,GAChB,QAAQ,GACR,gBAAgB,GAChB,gBAAgB,GAChB,eAAe,CAAA;AAEnB;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,uHAQgB,CAAA;AAE5C;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAK5D"}

package/dist/policy/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Policy module — Cedar policy engine wrapper (Phase 1 Step 1).
+ *
+ * Re-exports the Cedar engine factory + types. Test-only helpers
+ * (`__resetCedarEngineCache`, `__setCedarLoaderForTests`) are
+ * intentionally NOT re-exported here; tests import them from the
+ * module directly via `'../cedar-engine'`.
+ */
+export { createCedarEngine, CedarEngineUnavailableError, CedarParseError, buildValidationErrors, classifyCedarErrorMessage, } from './cedar-engine';
+export type { CedarEngine, CedarDecision, CedarError, CedarEntity, CedarEvaluateRequest, EvaluateInput, EvaluateResult, SchemaHandle, PolicySetHandle, PolicyValidationError, } from './cedar-engine';
+export { buildCedarEntities } from './cedar-entities';
+export type { CedarEntitiesInput, CedarEntityDescriptor, } from './cedar-entities';
+export { DECISION_VALUES, isDecision } from './decision';
+export type { Decision } from './decision';
+//# sourceMappingURL=index.d.ts.map

package/dist/policy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/policy/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC3B,eAAe,EACf,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAA;AAEvB,YAAY,EACV,WAAW,EACX,aAAa,EACb,UAAU,EACV,WAAW,EACX,oBAAoB,EACpB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,eAAe,EACf,qBAAqB,GACtB,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACrD,YAAY,EACV,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACxD,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA"}