@aws/dogwood-wasm 0.0.0-stage → 1.1.0

package/dogwood_wasm.d.ts

@@ -0,0 +1,597 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * A Dogwood field value. JSON values map to their Dogwood counterparts;
+ * non-integer numbers become decimals. Two tagged forms cover what JSON
+ * cannot express:
+ *
+ *  - `{ __entity: { type, id } }` — an entity reference
+ *  - `{ __decimal: "1.50" }` — a decimal with exact text preserved (a JS
+ *    number would round-trip `1.50` as `1.5`)
+ */
+export type DogwoodValue =
+| null
+| boolean
+| number
+| string
+| DogwoodValue[]
+| { __entity: EntityRef }
+| { __decimal: string }
+| { [key: string]: DogwoodValue };
+
+
+
+/** How the plain-text renderer lays out a phrase's children (a hint only). */
+export type Layout = "Inline" | "Block" | "Hanging";
+/** One node of an informalized policy: `template` has `{0}`, `{1}`, … slots for `children`. */
+export interface Phrase {
+    template: string;
+    children: Phrase[];
+    /** `[start, end)` byte range of the originating `.dw` node; absent for synthesized framing. */
+    span?: [number, number];
+    layout: Layout;
+}
+/** A policy set's informalization: an optional event-schema preamble, then one phrase tree per rule. */
+export interface Informalization {
+    /** Event-schema pins that restrict every temporal clause; absent if none apply. */
+    preamble?: Phrase;
+    rules: Phrase[];
+}
+
+
+
+/** The structured payload attached to a thrown Dogwood error as `.diagnostic`. */
+export interface DogwoodDiagnostic {
+    severity: Severity;
+    code?: string;
+    message: string;
+    labels?: Label[];
+    help?: string;
+    spanned: boolean;
+    /** Follow-on findings (e.g. the 2nd..Nth of a batch of parse errors). */
+    related?: Diagnostic[];
+}
+export interface DogwoodError extends Error {
+    diagnostic: DogwoodDiagnostic;
+}
+
+
+/**
+ * A per-policy summary from a successful parse (pre-lowering, schema-free).
+ */
+export interface PolicySummary {
+    /**
+     * Number of `temporal { … }` leaves in the policy.
+     */
+    temporal_count: number;
+    /**
+     * Whether the policy uses any temporal clause.
+     */
+    uses_temporal: boolean;
+    /**
+     * Every information-provider invocation, as `Ns::Fn` keys.
+     */
+    provider_invocations: string[];
+    /**
+     * Provider invocations naming a provider not declared in the service
+     * schema — a pre-lowering warning surfaced structurally.
+     */
+    undeclared_providers: string[];
+}
+
+/**
+ * A structured entity reference, deserialized from `{ type, id }`.
+ */
+export interface EntityRef {
+    /**
+     * Entity type, namespace included (`"Drupe::User"`).
+     */
+    type: string;
+    /**
+     * The raw, un-escaped entity id.
+     */
+    id: string;
+}
+
+/**
+ * One decision point's verdict, with its determining rules and any evaluation
+ * errors. History-only events (which yield no decision) contribute no entry.
+ */
+export interface TimepointVerdict {
+    /**
+     * 0-based index of this decision point in the decision stream.
+     */
+    index: number;
+    /**
+     * The event's wall-clock timestamp.
+     */
+    timestamp: number;
+    verdict: Verdict;
+    /**
+     * The `.dw` rule indices that determined the decision (empty for an
+     * implicit deny).
+     */
+    determining_rules: number[];
+    /**
+     * Any evaluation errors folded into this decision (a fail-closed deny
+     * carries them here).
+     */
+    errors: string[];
+}
+
+/**
+ * One diagnostic finding, owned and serializable — the CLI's projection of
+ * a frontend `miette::Diagnostic`. Used for the non-fatal channel (validation
+ * errors/warnings); the fatal channel is [`OpError`], which wraps one of
+ * these plus the source text for rendering.
+ */
+export interface Diagnostic {
+    severity: Severity;
+    /**
+     * The diagnostic's stable code (e.g. `"temporal"`), if it has one.
+     */
+    code?: string;
+    message: string;
+    /**
+     * The labelled spans, in the order the diagnostic reports them. Empty for
+     * a span-less finding (e.g. an event-schema error that carries only a
+     * message).
+     */
+    labels: Label[];
+    help?: string;
+    /**
+     * Whether this finding has any source-anchored span. `false` means the CLI
+     * cannot underline a snippet for it — only the message is available.
+     */
+    spanned: boolean;
+}
+
+/**
+ * One entity supplied to a decision: its identity plus the attributes and
+ * direct parents a policy may read (`principal.dept`, `principal in Group`).
+ */
+export interface EntityInput {
+    /**
+     * Entity type, namespace included (`"Drupe::User"`).
+     */
+    type: string;
+    /**
+     * The raw, un-escaped entity id.
+     */
+    id: string;
+    /**
+     * Attributes, `name -> value`. Validated against the action schema at
+     * decision time, so a wrong-typed attribute fails closed.
+     */
+    attrs?: Record<string, DogwoodValue>;
+    /**
+     * **Direct** parents (`memberOf` edges). Cedar computes the transitive
+     * closure, so only direct parents are supplied.
+     */
+    parents?: EntityRef[];
+}
+
+/**
+ * One event fed to a [`DogwoodAuthorizer`] — the JS analog of the frontend's
+ * `Event`, and a mirror of the `.log` wire format's components.
+ */
+export interface EventInput {
+    /**
+     * The **fully qualified** Cedar action id — `"Drupe::Action::Read"`.
+     * Split on the **last** `::`, so an action id containing an interior `::`
+     * is not supported (Cedar permits it; Dogwood's own `Event::builder` has
+     * the same restriction).
+     *
+     * Must name an action the schema declares — see
+     * [`actions`](DogwoodAuthorizer::actions). A *bare* id (`"Read"`) would
+     * otherwise parse and then not resolve, denying with an empty
+     * [`errors`](AuthorizerDecision::errors) and so being indistinguishable
+     * from "policy said no"; it is rejected instead, with the qualified id
+     * suggested.
+     */
+    action: string;
+    /**
+     * The event kind. `"request"` (the default) is a decision point;
+     * `"response"` / `"error"` are history-only — they update temporal state
+     * and return `undefined`. Which kinds exist, and which decide, is set by
+     * the event schema — see [`eventKinds`](DogwoodAuthorizer::event_kinds) and
+     * [`decisionKinds`](DogwoodAuthorizer::decision_kinds).
+     *
+     * A kind the schema does not declare is **rejected**. Left to the engine it
+     * would be treated as history-only, so a typo (`"requst"`) would silently
+     * yield no decision forever instead of failing loudly.
+     */
+    kind?: string;
+    /**
+     * Wall-clock timestamp, in **seconds** — the unit the temporal windows are
+     * defined in (`1h` is 3600). From JS that means
+     * `Math.floor(Date.now() / 1000)`, *not* `Date.now()`: passing
+     * milliseconds silently inflates every window by 1000×, so a `within 1h`
+     * predicate would match only events from the last 3.6 seconds.
+     *
+     * Timestamps order events for the temporal operators, so this must be
+     * **non-decreasing** across calls on one instance — one instance is one
+     * ordered history. A timestamp before the previous event's is rejected
+     * rather than silently producing wrong temporal answers; see
+     * [`lastTimestamp`](DogwoodAuthorizer::last_timestamp).
+     */
+    timestamp?: number;
+    /**
+     * The request principal. Setting it makes the event request-wrapping.
+     */
+    principal?: EntityRef;
+    /**
+     * The request resource. Setting it makes the event request-wrapping.
+     */
+    resource?: EntityRef;
+    /**
+     * The **durable temporal record**: `group -> { name -> value }`, read by
+     * temporal predicates in later events. Distinct from
+     * [`context`](Self::context) — see the module docs.
+     */
+    logged?: Record<string, Record<string, DogwoodValue>>;
+    /**
+     * The **per-decision Cedar request context**: `group -> { name -> value }`,
+     * read by a policy as `context.<group>.<name>`. Never persisted.
+     */
+    context?: Record<string, Record<string, DogwoodValue>>;
+    /**
+     * The entity store for this decision — attributes and hierarchy for any
+     * entity the policy names.
+     */
+    entities?: EntityInput[];
+}
+
+/**
+ * One labelled span within the source a diagnostic points at: a byte range
+ * and an optional per-label message. Offsets index the `.dw` (or schema)
+ * source text the CLI passed in.
+ */
+export interface Label {
+    /**
+     * Byte offset of the label's start in the source.
+     */
+    start: number;
+    /**
+     * Byte length of the labelled span.
+     */
+    len: number;
+    /**
+     * The label's own message, if it carries one.
+     */
+    message?: string;
+}
+
+/**
+ * The Cedar artifacts produced by lowering a `.dw` policy set.
+ */
+export interface LowerArtifacts {
+    /**
+     * The lowered Cedar policies, rendered to `.cedar` text.
+     */
+    cedar_policies: string;
+    /**
+     * The augmented Cedar action schema, as `.cedarschema` text.
+     */
+    cedar_schema: string;
+    /**
+     * The augmented schema in Cedar JSON form.
+     */
+    cedar_schema_json: string;
+    /**
+     * Whether the exported Cedar fully reproduces the policy semantics.
+     * `false` when temporal/provider fields were hoisted (those need Dogwood
+     * at authorize time — the Cedar alone is not self-sufficient).
+     */
+    self_contained: boolean;
+    /**
+     * The hoisted temporal leaf ids (`context.<id>` slots), for reference.
+     */
+    temporal_fields: string[];
+    /**
+     * The hoisted provider field ids (`context.providers.<id>` slots).
+     */
+    provider_fields: string[];
+    /**
+     * The event kinds that are decision points.
+     */
+    decision_kinds: string[];
+}
+
+/**
+ * The decision for one event: the verdict plus why.
+ */
+export interface AuthorizerDecision {
+    /**
+     * 0-based index of this decision in the authorizer's decision stream
+     * (history-only events do not advance it).
+     */
+    index: number;
+    /**
+     * The event's timestamp, echoed back.
+     */
+    timestamp: number;
+    verdict: Verdict;
+    /**
+     * `true` exactly when `verdict === "allow"`: the policy allowed **and**
+     * evaluation raised no errors. Stricter than Dogwood's own
+     * `Response::allowed`, which is Cedar's decision alone — Cedar skips a
+     * rule whose condition errors, so an errored `forbid` would otherwise let
+     * a `permit` through.
+     */
+    allowed: boolean;
+    /**
+     * The `.dw` rule indices that determined the decision. Empty for an
+     * implicit deny (no rule matched) and for a fail-closed deny (`errors`
+     * non-empty).
+     */
+    determining_rules: number[];
+    /**
+     * Evaluation errors folded into this decision. Any error forces a deny,
+     * so a non-empty `errors` means *something went wrong*, not *policy said
+     * no*.
+     */
+    errors: string[];
+}
+
+/**
+ * The per-timepoint verdict stream from replaying a trace.
+ */
+export interface ReplayReport {
+    verdicts: TimepointVerdict[];
+}
+
+/**
+ * The result of `check-parse`: the policy set parsed and macro-expanded, with
+ * per-policy structural summaries. Syntax and macro errors only — schema-
+ * dependent checks (unknown attributes, type errors) are deferred to
+ * `validate`.
+ */
+export interface CheckParseReport {
+    policy_count: number;
+    policies: PolicySummary[];
+}
+
+/**
+ * The result of `explain`: the policy set's deterministic informalization —
+ * the structured [`Informalization`] (one phrase tree per rule, each phrase
+ * carrying its `.dw` span) and the same rendered as indented plain text.
+ */
+export interface ExplainReport {
+    /**
+     * The phrase trees (JSON consumers walk this; spans are `[start, end)`
+     * byte offsets into the `.dw` source).
+     */
+    informalization: Informalization;
+    /**
+     * The plain-text rendering (what human mode prints).
+     */
+    text: string;
+}
+
+/**
+ * The result of `validate`: whether the policy set type-checks against the
+ * schema, plus every finding. A fatal parse/lower error is returned as the
+ * `Err` channel instead; this report covers the type-check phase, which
+ * accumulates all findings rather than stopping at the first.
+ */
+export interface ValidateReport {
+    /**
+     * True iff there are no validation errors (warnings do not fail).
+     */
+    passed: boolean;
+    /**
+     * True iff there are neither errors nor warnings.
+     */
+    passed_without_warnings: boolean;
+    errors: Diagnostic[];
+    warnings: Diagnostic[];
+}
+
+/**
+ * The result of a standalone schema check: whether the artifact is
+ * well-formed, and any warnings (a valid-but-suspect schema).
+ */
+export interface SchemaCheckReport {
+    /**
+     * The artifact kind that was checked (`"action"`, `"event"`, `"providers"`).
+     */
+    kind: string;
+    /**
+     * True iff the artifact parsed and is well-formed.
+     */
+    ok: boolean;
+    /**
+     * Non-fatal warnings (from the action-schema and providers checks).
+     */
+    warnings: string[];
+}
+
+/**
+ * The severity of a [`Diagnostic`], projected from `miette::Severity`
+ * (which defaults to `Error` when a diagnostic does not specify one).
+ */
+export type Severity = "error" | "warning" | "advice";
+
+/**
+ * Whether a decision point allowed or denied — the CLI's own verdict type
+ * (not cedar's `Decision`, which is not ours to serialize).
+ */
+export type Verdict = "allow" | "deny";
+
+
+/**
+ * A **stateful, live** Dogwood authorizer: lower a policy set once, then feed
+ * events as they happen and get a decision per event, with temporal history
+ * accumulating across calls.
+ *
+ * This is the counterpart to the one-shot [`replay`](crate::replay): same
+ * engine and same lowering, but the caller drives the loop. Because it holds
+ * temporal state, one instance corresponds to one history — see
+ * [`reset`](DogwoodAuthorizer::reset).
+ */
+export class DogwoodAuthorizer {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Authorize one event.
+     *
+     * Returns the [`AuthorizerDecision`] for a decision-kind event (by
+     * default, `kind: "request"`), or `undefined` for a history-only event —
+     * which still updates temporal history, and is how a host records the
+     * `response` half of a call so later policies can correlate against it.
+     *
+     * Throws a `DogwoodError` if the event is malformed (a missing `action`, a
+     * bad `__entity` tag, a wrong-typed field), **too large** (a value nested
+     * deeper than 128 levels, or past the size limits in `bounds`), or
+     * **rejected** by
+     * [`check`](Self::check) — an action or kind the schema does not declare, or
+     * a timestamp before the previous event's. Either way the instance is left
+     * **usable** and the temporal history untouched: the event is validated
+     * before it is observed, so a failed call is a no-op and the next call
+     * decides normally.
+     *
+     * A *policy* problem is never thrown: an evaluation failure comes back as a
+     * fail-closed `deny` with the cause in
+     * [`errors`](AuthorizerDecision::errors).
+     *
+     * The parameter is taken as a `JsValue` and deserialized here rather than
+     * declared as `EventInput` directly, which is load-bearing: wasm-bindgen
+     * acquires the `&mut self` borrow *before* converting arguments, so a
+     * conversion that fails propagates the exception without releasing the
+     * borrow — permanently poisoning the instance (every later call, `free()`
+     * included, then fails with "recursive use of an object"). Converting
+     * inside the body means the failure is an ordinary `Err` return and the
+     * borrow is released. `unchecked_param_type` keeps the TypeScript
+     * signature `EventInput`.
+     */
+    isAuthorized(event: EventInput): AuthorizerDecision | undefined;
+    /**
+     * Lower `source` against `actionSchema` and build a fresh authorizer with
+     * empty temporal history. Throws a `DogwoodError` (with `.diagnostic`) on
+     * a parse, macro, lowering, or schema failure — the same error contract as
+     * every other operation in these bindings.
+     *
+     * The trailing arguments are the optional service-schema overrides
+     * (event-schema DSL text, `providers.json` text, macro-library text);
+     * omit them for the defaults.
+     */
+    constructor(source: string, action_schema: string, event_schema?: string | null, providers?: string | null, macros?: string | null);
+    /**
+     * Drop all accumulated temporal history and start over, re-lowering the
+     * original sources. Cheaper than constructing a new instance only in that
+     * the caller need not keep the sources around; the lowering cost is the
+     * same. The decision index restarts at 0.
+     */
+    reset(): void;
+    /**
+     * Every **fully qualified** action id this instance can decide
+     * (`["Drupe::Action::Read", …]`) — the actions the action schema declares.
+     * An event naming anything else is rejected, so a host that maps its own
+     * operation names onto Cedar actions can check the mapping against this
+     * once at startup rather than discovering a gap one denied request at a
+     * time.
+     */
+    readonly actions: string[];
+    /**
+     * How many decisions this instance has returned — the `index` the next
+     * decision will carry.
+     */
+    readonly decisionCount: number;
+    /**
+     * The event kinds that are decision points under this instance's event
+     * schema (`["request"]` by default) — the kinds for which
+     * [`isAuthorized`](Self::is_authorized) returns a decision rather than
+     * `undefined`.
+     *
+     * A kind in [`eventKinds`](Self::event_kinds) but not here is history-only:
+     * it is accepted, it updates temporal state, and it yields no verdict.
+     */
+    readonly decisionKinds: string[];
+    /**
+     * Every event kind this instance's event schema declares, decision points
+     * and history-only alike (`["error", "request", "response"]` by default).
+     * Any other kind is rejected — see [`isAuthorized`](Self::is_authorized).
+     */
+    readonly eventKinds: string[];
+    /**
+     * The timestamp of the most recent event observed, or `undefined` before
+     * the first (and after a [`reset`](Self::reset)). The next event's
+     * timestamp must be at least this.
+     *
+     * Widened to `f64` so the TypeScript type is `number`, matching
+     * [`AuthorizerDecision::timestamp`] and the `timestamp` a host passes in.
+     * An `i64` would come back a `BigInt`, which compares false against every
+     * plain number it is likely to be compared with (`5n == 5` is true but
+     * `5n === 5` is false, and mixed arithmetic throws) — a needless trap on a
+     * value that is a count of seconds and so nowhere near `f64`'s exact-integer
+     * limit.
+     */
+    readonly lastTimestamp: number | undefined;
+}
+
+/**
+ * Check a Cedar action schema (`.cedarschema`) in isolation.
+ */
+export function checkActionSchema(source: string): SchemaCheckReport;
+
+/**
+ * Check an event-schema DSL (`.dwschema`) in isolation.
+ */
+export function checkEventSchema(source: string): SchemaCheckReport;
+
+/**
+ * Parse and macro-expand a `.dw` policy set, reporting syntax/macro errors and
+ * per-policy structural summaries. Needs no action schema.
+ */
+export function checkParse(source: string, event_schema?: string | null, providers?: string | null, macros?: string | null): CheckParseReport;
+
+/**
+ * Check an information-provider declarations file (`providers.json`) in
+ * isolation.
+ */
+export function checkProviders(json: string): SchemaCheckReport;
+
+/**
+ * Parse (with macro expansion) and informalize a `.dw` policy set into
+ * deterministic semi-English, rule by rule. The action schema is optional:
+ * with it, the single declared namespace is dropped from names. Nothing is
+ * validated — an invalid-but-parsable policy is still explained.
+ */
+export function explain(source: string, action_schema?: string | null, event_schema?: string | null, providers?: string | null, macros?: string | null): ExplainReport;
+
+/**
+ * Module start hook, invoked automatically on load. In a development build
+ * (feature `dev`, `npm run build:dev`) it installs a panic hook so a Rust panic
+ * surfaces as a readable `console.error`; a release build installs nothing,
+ * and a panic aborts with an opaque `unreachable` without logging its message.
+ */
+export function init(): void;
+
+/**
+ * Lower a `.dw` policy set to Cedar and return the emitted artifacts (policies
+ * and augmented schema, in text and Cedar-JSON forms).
+ */
+export function lower(source: string, action_schema: string, event_schema?: string | null, providers?: string | null, macros?: string | null): LowerArtifacts;
+
+/**
+ * Generate a Cedar action schema (`.cedarschema` text) from an MCP
+ * `tools/list` manifest, layered on the embedded Drupe template.
+ */
+export function mcpToCedarSchema(manifest_json: string): string;
+
+/**
+ * Lower, then drive a `.log` event trace through a stateful authorizer,
+ * returning the per-decision verdict stream.
+ *
+ * Any evaluation error forces a deny, exactly as in
+ * `DogwoodAuthorizer::isAuthorized` (see [`fail_closed`]).
+ */
+export function replay(source: string, action_schema: string, log: string, event_schema?: string | null, providers?: string | null, macros?: string | null): ReplayReport;
+
+/**
+ * Lower against the Cedar action schema and type-check. Fatal parse/lower
+ * errors throw; a successful lower with type findings returns the report.
+ */
+export function validate(source: string, action_schema: string, event_schema?: string | null, providers?: string | null, macros?: string | null): ValidateReport;