@corbado/observe 1.14.1 → 1.15.1

package/dist/manifest/index.d.mts

@@ -0,0 +1,309 @@
+/**
+ * Collection manifest v2 (`corbado.collection/v2`): the descriptor contract shared by the SDK, the autocapture
+ * library and the autocapture tools, plus the shared vocabulary (collection levels, categories, kinds).
+ *
+ * Descriptors are DATA for the tools (`ac manifest`, the gate) and are never part of a shipped bundle: runtime
+ * code never imports `src/manifest/**` (checked by `manifest.test.ts` and `scripts/check-data-guards.mjs`).
+ * Import them from the `@corbado/observe/manifest` subpath (Node ESM: `@corbado/observe/dist/manifest/index.mjs`).
+ *
+ * Model: feature-docs/autocapture-releases/manifest-model-v1.html (v1.3), sections 0, 0b, 2, 3, 6.
+ *
+ * Changes to the shapes below are additive only (the tools of older and newer packages read them).
+ */
+/** Non-value collection levels: they reveal nothing about the content. */
+type NonValueLevel = "presence" | "empty" | "interaction" | "shown" | "request-metadata" | "ceremony" | "equality";
+/** Value collection levels: derived from the value, they reveal something about it. */
+type ValueLevel = "size" | "class" | "enum" | "pseudonym" | "partial" | "pattern" | "raw";
+/** One collection level per field (JSON key `level`). `generated` is not a level: generated ids are an output. */
+type CollectionLevel = NonValueLevel | ValueLevel;
+/** Non-value levels (order within a kind's ladder: see {@link KIND_LADDERS}). */
+declare const NON_VALUE_LEVELS: readonly NonValueLevel[];
+/** Value levels ordered by what a reader learns about the content (section 2, "The order of value levels"). */
+declare const VALUE_LEVELS: readonly ValueLevel[];
+/** What a field is about (the subject), never derived from its level. */
+type Category = "secret" | "personal-identifier" | "opaque-identifier" | "personal-data" | "device" | "technical";
+declare const CATEGORIES: readonly Category[];
+/**
+ * Allowed VALUE levels per category (section 3). Non-value levels (and `equality`) are allowed for every category.
+ * `personal-identifier` pseudonyms must be keyed or project-salted; `personal-data` patterns closed or structural.
+ */
+declare const CATEGORY_VALUE_LEVELS: {
+    readonly [C in Category]: readonly ValueLevel[];
+};
+/** Source kinds (section 1). */
+type SourceKind = "dom-input" | "dom-element" | "url" | "request" | "storage" | "host-config" | "host-event" | "browser-api" | "page/window" | "generated"
+/** Additive (WP3 follow-up): fields the SDK itself adds to every record it sends (ordering counters). */
+ | "record";
+/**
+ * One ladder per kind (section 2): non-value levels below value levels, each in its order. `equality` is allowed on
+ * every kind with values and is not listed per ladder.
+ */
+declare const KIND_LADDERS: {
+    readonly [K in Exclude<SourceKind, "generated">]: {
+        readonly nonValue: readonly NonValueLevel[];
+        readonly value: readonly ValueLevel[];
+    };
+};
+/** A field id `<source key>#<field path>`, a `generated:` / `storage:` / `telemetry:` / `transport:` id. */
+type ManifestId = string;
+/** A reviewed collector with an algorithm between browser object and output (section 0b, one card each). */
+interface CapabilityDescriptor {
+    /** `sdk:input`, `ac:ceremony`, `sdk:window`, ... (rendered as `<key>@<version>`, referenced by fields' `via`). */
+    key: string;
+    version: number;
+    /** Plain customer language (section 0b). */
+    title: string;
+    why: string;
+    collects: string[];
+    /** `proof` = the id of a test in this repo (`<key>@<version>#never.<slug>`, part of the test's title). */
+    never: {
+        text: string;
+        proof: string;
+    }[];
+    modes?: Record<string, string>;
+    /** Named options a project declaration can set, e.g. `passkeyReference`. */
+    options?: {
+        name: string;
+        adds: string;
+    }[];
+    /** What the capability does on the page beyond reading; `when` = the build switch that enables it. */
+    sideEffects?: SideEffect[];
+    review?: string;
+    /** Additive (WP2): short plain-language line shown under the card, e.g. "used on: input fields". */
+    usedOn?: string;
+    /** Additive (WP2): the build switch that removes the whole capability from builds that turn it off. */
+    when?: string;
+}
+/**
+ * Conditions shared by descriptor entries (all additive, all optional):
+ * - `when`: the build switch or config flag (static config / `build.config`) the entry depends on; `"!<name>"` = only
+ *   when it is off (e.g. `"!static"`: only with a downloaded config).
+ * - `requires`: the never-ship item (id of the tools' never-ship list, e.g. `"cross-origin-session"`,
+ *   `"sdk-operations"`) whose optional code produces the entry; omit the entry when that code is not in the bundle.
+ */
+interface Conditional {
+    when?: string;
+    requires?: string;
+}
+/** Something a capability does on the page beyond reading (shown in the overview's behavior list). */
+interface SideEffect extends Conditional {
+    /** `<area>.<slug>`, stable across versions. Entries of several capabilities with the same id describe one effect. */
+    id: string;
+    text: string;
+    /** Build switch / config flag that enables it, e.g. `"aap"`, `"privateMode"`, `"pmd"`. */
+    when?: string;
+}
+/** Gateways without an algorithm and the output gateways (sections 4 and 6). */
+interface GatewayDescriptor {
+    key: string;
+    version: number;
+    /** Always-collected fields. */
+    fields?: GatewayField[];
+    generated?: GeneratedEntry[];
+    stored?: StoredEntry[];
+    telemetry?: TelemetryEntry[];
+    /** Additive (WP1/WP2): the source the `fields` belong to; field ids are `<source.key>#<path>`. */
+    source?: {
+        key: string;
+        kind: SourceKind | string;
+        title?: string;
+    };
+    /** Additive (WP2): plain-language title of the gateway. */
+    title?: string;
+    /** Additive (WP2): transport facts (`transport:<fact>`), only on the transport gateway. */
+    transport?: TransportFact[];
+}
+interface GatewayField extends Conditional {
+    path: string;
+    /** A category, or `"role"`: inherit the category of the input role the field is read from. */
+    category: Category | "role" | string;
+    level: CollectionLevel | string;
+    label: string;
+    /** Additive (WP2): capability that produces the field, `<key>@<version>`. */
+    via?: string;
+    /** Additive (WP2): parameters of the level (enum values, pattern, template, buckets, ...). */
+    transform?: Record<string, unknown>;
+    /** Additive (WP2): synthetic examples fitting the level. */
+    examples?: (string | number | boolean)[];
+    /** Additive (WP2): build switch the field depends on (absent in builds that turn it off). */
+    when?: string;
+    /** Additive (WP1): what an opaque-identifier field points to (credential, browser, session, tab, flow). */
+    pointsTo?: string;
+}
+/**
+ * A generated identifier (an output type, not a collection level).
+ * - `lifetime`: `"event"`, `"page-load"`, `"tab"`, `"persistent"` or an ISO 8601 duration (e.g. `"PT30M"` of
+ *   inactivity).
+ * - `exposedTo`: who besides Corbado can see it, e.g. `"corbado"`, `"page scripts (getSessionId)"`,
+ *   `"page scripts (local storage)"`.
+ */
+interface GeneratedEntry extends Conditional {
+    id: string;
+    category: Category | string;
+    pointsTo: string;
+    lifetime: string;
+    scope?: string;
+    exposedTo: string[];
+    /** Additive (WP2): plain-language label. */
+    label?: string;
+    /** Additive (WP2): build switch / config flag the entry depends on. */
+    when?: string;
+}
+/**
+ * Something the bundle writes to the browser.
+ * - `area`: `"local"`, `"session"`, `"cookie"`, `"indexeddb"`, `"opfs"`, `"web-locks"`, ...
+ * - `scope`: `"tab"`, `"origin"`, `"cookie domain + path"`.
+ * - `retention`: an ISO 8601 duration (enforced by code), `"tab"` (sessionStorage), `"PT0S"` (removed at once) or
+ *   `"persistent"`.
+ * - `owner`: `"sdk"`, `"project"`, `"third-party (<package>)"`.
+ * - `contents`: field and generated ids (typed references); `"sent:events"` = the whole queued event as sent.
+ * - `when` (see {@link Conditional}): without `otherwise` the entry is absent when `when` does not hold; with
+ *   `otherwise` the entry stays, merged with `otherwise` (e.g. a cache a build does not write but still removes).
+ */
+interface StoredEntry extends Conditional {
+    id: string;
+    area: string;
+    scope: string;
+    retention: string;
+    owner: string;
+    contents: string[];
+    /** Additive (WP2): the keys as written (`cbo_<name>_<projectId>`; `*` = the project id or a family). */
+    keys?: string[];
+    /** Additive (WP2): plain-language label. */
+    label?: string;
+    /** Additive (WP2): whether `retention` is enforced by code (purged), not only described. */
+    enforced?: boolean;
+    /** Additive (WP2): build switch / config flag the entry depends on. */
+    when?: string;
+    /**
+     * Additive (v2 descriptors): the bundle never writes the entry, it only removes it when found (keys of older
+     * versions). Such an entry keeps nothing (`contents` empty); its `retention` is `"PT0S"` for older tools.
+     */
+    deleteOnly?: boolean;
+    /** Additive (v2 descriptors): a plain-language remark shown with the entry. */
+    note?: string;
+    /** Additive (v2 descriptors): what the entry becomes when its `when` does not hold (merged over the entry). */
+    otherwise?: StoredVariant;
+}
+/** Additive (v2 descriptors): the fields of a {@link StoredEntry} that its `otherwise` variant may replace. */
+type StoredVariant = Partial<Pick<StoredEntry, "retention" | "enforced" | "contents" | "label" | "deleteOnly" | "note" | "keys">>;
+interface TelemetryEntry {
+    kind: string;
+    fields: string[];
+    /** Additive (WP2): plain-language label. */
+    label?: string;
+}
+/** Additive (WP2): what the transport sends besides the events (`transport:<fact>`). */
+interface TransportFact {
+    id: string;
+    label: string;
+    /** `"browser"` = added by the browser, not by the SDK. */
+    addedBy: "sdk" | "browser";
+    when?: string;
+}
+
+/**
+ * `ac:ceremony@1` (SDK part): the WebAuthn allowlist (`src/utils/webauthn-ceremony.ts`), used by the sanitizers in
+ * builds that define `__CBO_DATA_CEREMONY__ = true` (build switch `ceremony`). The library's credentials wrapper and
+ * its endpoint reductions are the callers (second entry point: WebAuthn payloads in request and response bodies).
+ * The side effects are the library's (`@corbado/autocapture` `src/readers/credentials.ts`): it wraps the two methods;
+ * the container proxy is used only where the runtime's server config allows it (`aap` = `"c1"`) and the methods
+ * themselves cannot be wrapped.
+ */
+declare const AC_CEREMONY: CapabilityDescriptor;
+
+/**
+ * Values the integration hands to the SDK's API that the SDK keeps in its own storage (referenced by
+ * `sdk:own-storage`). The full host contract (init options, page config) is gap G15 and follows with the library's
+ * host-config gateway.
+ */
+declare const SDK_API: GatewayDescriptor;
+
+/**
+ * Device gateway (`src/readers/device.ts`, collected by `src/device.ts`): fixed readers, no capability. Sent once
+ * per page with the first events (device info), together with the generated device handle and tab id (see
+ * the generated-ids gateway).
+ */
+declare const SDK_DEVICE: GatewayDescriptor;
+
+/**
+ * Generated-ids output gateway (`outputs.sent.generated`, gap G3). Rule (model 11e): technical if an id lives at most
+ * one tab or flow and never leaves the tab, otherwise opaque-identifier. Every id below is sent to Corbado, so all
+ * random ids are opaque-identifier. The sequence counters are not ids: they are technical fields of each record
+ * ({@link SDK_RECORD}).
+ */
+declare const SDK_GENERATED: GatewayDescriptor;
+/**
+ * Fields the SDK adds to every record it sends (decided 2026-11-08: the sequence counters are a technical field of
+ * the event, not a generated id). Source kind `record`: nothing is read from the page.
+ */
+declare const SDK_RECORD: GatewayDescriptor;
+
+/**
+ * Own-storage output gateway (`outputs.stored`, gap G2): every key the SDK writes. Keys are written as
+ * `cbo_<name>_<projectId>` (`*` below). `retention` is enforced by code where `enforced` is true: the outboxes and
+ * the email-link notes only in builds with `__CBO_DATA_RETENTION__` (build switch `retention`); without it the
+ * outboxes keep entries up to their caps (500 events, 1000 low events) and expired email-link notes stay until the
+ * next write. Contents reference field and generated ids; `sent:events` = whole queued records as they are sent.
+ *
+ * Not listed: the private-mode library's temporary test databases, test directory and `test` entry (removed at once,
+ * nothing kept on the device): a side effect of `sdk:private-mode@1`. Entries with `otherwise` stay in the manifest
+ * when their `when` does not hold, merged with the variant (contract `StoredEntry.otherwise`).
+ */
+declare const SDK_OWN_STORAGE: GatewayDescriptor;
+
+/**
+ * Page gateway (`src/readers/page.ts`), declared as it behaves today: the page path is sent raw (no templates yet,
+ * gap G8) with every batch's first event; query keys stay, their values are masked unless the config allowlists the
+ * key (`sourcePathQuery` / `sourcePathQueryAllow`). Templates, declared query reductions and the navigation entry
+ * follow with the G8 change.
+ */
+declare const SDK_PAGE: GatewayDescriptor;
+
+/**
+ * `sdk:input@1`: the input gateway (`src/readers/input.ts`, `src/readers/input-paste.ts`, collectors in
+ * `src/low-events/`), declared as it behaves today (v1). Inside the gateway it reads the field's LENGTH (and a
+ * checkbox's checked state) to tell typing, pasting, clearing and several-characters-at-once changes apart; neither
+ * the value nor the length leaves it. A value-free v2 comes later (model section 13, "Later").
+ * Side effect: the library's input reader (`@corbado/autocapture` `onInput`, `src/readers/inputs.ts`) watches the
+ * document for added fields; `ac:element@1` lists the same effect (same id) for element roles.
+ */
+declare const SDK_INPUT: CapabilityDescriptor;
+
+/**
+ * `sdk:password-managers@1`: password-manager detection (`src/readers/password-manager-extensions.ts`, sampled by
+ * `src/utils/password-manager-sampler.ts`). Compiled out with `__CBO_DATA_PMD__ = false` (build switch `pmd`).
+ */
+declare const SDK_PASSWORD_MANAGERS: CapabilityDescriptor;
+
+/**
+ * `sdk:private-mode@1`: private-mode detection (`src/readers/private-mode.ts`, the third-party library
+ * detectincognitojs). Compiled out with `__CBO_DATA_PRIVATE_MODE__ = false` (build switch `privateMode`).
+ * The library's temporary test databases, test directory and `test` storage entry are only this side effect: they
+ * are removed at once, so `sdk:own-storage` does not list them (nothing is kept on the device).
+ */
+declare const SDK_PRIVATE_MODE: CapabilityDescriptor;
+
+/**
+ * Transport output gateway (`src/transports/fetch.ts`, `src/readers/network.ts`): ingestion requests with fetch
+ * (keepalive, no credentials) and `sendBeacon` on page hide. Lists what leaves besides the events themselves.
+ */
+declare const SDK_TRANSPORT: GatewayDescriptor;
+
+/** `sdk:window@1`: the window gateway (`src/readers/window-events.ts`, `src/low-events/shared-window-observer.ts`). */
+declare const SDK_WINDOW: CapabilityDescriptor;
+
+/**
+ * `@corbado/observe/manifest`: collection manifest v2 descriptors of the SDK's gateways and capabilities, read by
+ * the autocapture tools from the package. Never imported by runtime code, so never part of a bundle.
+ */
+
+/** Every capability descriptor of this package. */
+declare const SDK_CAPABILITIES: readonly CapabilityDescriptor[];
+/** Every gateway descriptor of this package. */
+declare const SDK_GATEWAYS: readonly GatewayDescriptor[];
+/** WP1 names: the same lists. */
+declare const capabilities: CapabilityDescriptor[];
+declare const gateways: GatewayDescriptor[];
+
+export { AC_CEREMONY, CATEGORIES, CATEGORY_VALUE_LEVELS, type CapabilityDescriptor, type Category, type CollectionLevel, type Conditional, type GatewayDescriptor, type GatewayField, type GeneratedEntry, KIND_LADDERS, type ManifestId, NON_VALUE_LEVELS, type NonValueLevel, SDK_API, SDK_CAPABILITIES, SDK_DEVICE, SDK_GATEWAYS, SDK_GENERATED, SDK_INPUT, SDK_OWN_STORAGE, SDK_PAGE, SDK_PASSWORD_MANAGERS, SDK_PRIVATE_MODE, SDK_RECORD, SDK_TRANSPORT, SDK_WINDOW, type SideEffect, type SourceKind, type StoredEntry, type StoredVariant, type TelemetryEntry, type TransportFact, VALUE_LEVELS, type ValueLevel, capabilities, gateways };

package/dist/manifest/index.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Collection manifest v2 (`corbado.collection/v2`): the descriptor contract shared by the SDK, the autocapture
+ * library and the autocapture tools, plus the shared vocabulary (collection levels, categories, kinds).
+ *
+ * Descriptors are DATA for the tools (`ac manifest`, the gate) and are never part of a shipped bundle: runtime
+ * code never imports `src/manifest/**` (checked by `manifest.test.ts` and `scripts/check-data-guards.mjs`).
+ * Import them from the `@corbado/observe/manifest` subpath (Node ESM: `@corbado/observe/dist/manifest/index.mjs`).
+ *
+ * Model: feature-docs/autocapture-releases/manifest-model-v1.html (v1.3), sections 0, 0b, 2, 3, 6.
+ *
+ * Changes to the shapes below are additive only (the tools of older and newer packages read them).
+ */
+/** Non-value collection levels: they reveal nothing about the content. */
+type NonValueLevel = "presence" | "empty" | "interaction" | "shown" | "request-metadata" | "ceremony" | "equality";
+/** Value collection levels: derived from the value, they reveal something about it. */
+type ValueLevel = "size" | "class" | "enum" | "pseudonym" | "partial" | "pattern" | "raw";
+/** One collection level per field (JSON key `level`). `generated` is not a level: generated ids are an output. */
+type CollectionLevel = NonValueLevel | ValueLevel;
+/** Non-value levels (order within a kind's ladder: see {@link KIND_LADDERS}). */
+declare const NON_VALUE_LEVELS: readonly NonValueLevel[];
+/** Value levels ordered by what a reader learns about the content (section 2, "The order of value levels"). */
+declare const VALUE_LEVELS: readonly ValueLevel[];
+/** What a field is about (the subject), never derived from its level. */
+type Category = "secret" | "personal-identifier" | "opaque-identifier" | "personal-data" | "device" | "technical";
+declare const CATEGORIES: readonly Category[];
+/**
+ * Allowed VALUE levels per category (section 3). Non-value levels (and `equality`) are allowed for every category.
+ * `personal-identifier` pseudonyms must be keyed or project-salted; `personal-data` patterns closed or structural.
+ */
+declare const CATEGORY_VALUE_LEVELS: {
+    readonly [C in Category]: readonly ValueLevel[];
+};
+/** Source kinds (section 1). */
+type SourceKind = "dom-input" | "dom-element" | "url" | "request" | "storage" | "host-config" | "host-event" | "browser-api" | "page/window" | "generated"
+/** Additive (WP3 follow-up): fields the SDK itself adds to every record it sends (ordering counters). */
+ | "record";
+/**
+ * One ladder per kind (section 2): non-value levels below value levels, each in its order. `equality` is allowed on
+ * every kind with values and is not listed per ladder.
+ */
+declare const KIND_LADDERS: {
+    readonly [K in Exclude<SourceKind, "generated">]: {
+        readonly nonValue: readonly NonValueLevel[];
+        readonly value: readonly ValueLevel[];
+    };
+};
+/** A field id `<source key>#<field path>`, a `generated:` / `storage:` / `telemetry:` / `transport:` id. */
+type ManifestId = string;
+/** A reviewed collector with an algorithm between browser object and output (section 0b, one card each). */
+interface CapabilityDescriptor {
+    /** `sdk:input`, `ac:ceremony`, `sdk:window`, ... (rendered as `<key>@<version>`, referenced by fields' `via`). */
+    key: string;
+    version: number;
+    /** Plain customer language (section 0b). */
+    title: string;
+    why: string;
+    collects: string[];
+    /** `proof` = the id of a test in this repo (`<key>@<version>#never.<slug>`, part of the test's title). */
+    never: {
+        text: string;
+        proof: string;
+    }[];
+    modes?: Record<string, string>;
+    /** Named options a project declaration can set, e.g. `passkeyReference`. */
+    options?: {
+        name: string;
+        adds: string;
+    }[];
+    /** What the capability does on the page beyond reading; `when` = the build switch that enables it. */
+    sideEffects?: SideEffect[];
+    review?: string;
+    /** Additive (WP2): short plain-language line shown under the card, e.g. "used on: input fields". */
+    usedOn?: string;
+    /** Additive (WP2): the build switch that removes the whole capability from builds that turn it off. */
+    when?: string;
+}
+/**
+ * Conditions shared by descriptor entries (all additive, all optional):
+ * - `when`: the build switch or config flag (static config / `build.config`) the entry depends on; `"!<name>"` = only
+ *   when it is off (e.g. `"!static"`: only with a downloaded config).
+ * - `requires`: the never-ship item (id of the tools' never-ship list, e.g. `"cross-origin-session"`,
+ *   `"sdk-operations"`) whose optional code produces the entry; omit the entry when that code is not in the bundle.
+ */
+interface Conditional {
+    when?: string;
+    requires?: string;
+}
+/** Something a capability does on the page beyond reading (shown in the overview's behavior list). */
+interface SideEffect extends Conditional {
+    /** `<area>.<slug>`, stable across versions. Entries of several capabilities with the same id describe one effect. */
+    id: string;
+    text: string;
+    /** Build switch / config flag that enables it, e.g. `"aap"`, `"privateMode"`, `"pmd"`. */
+    when?: string;
+}
+/** Gateways without an algorithm and the output gateways (sections 4 and 6). */
+interface GatewayDescriptor {
+    key: string;
+    version: number;
+    /** Always-collected fields. */
+    fields?: GatewayField[];
+    generated?: GeneratedEntry[];
+    stored?: StoredEntry[];
+    telemetry?: TelemetryEntry[];
+    /** Additive (WP1/WP2): the source the `fields` belong to; field ids are `<source.key>#<path>`. */
+    source?: {
+        key: string;
+        kind: SourceKind | string;
+        title?: string;
+    };
+    /** Additive (WP2): plain-language title of the gateway. */
+    title?: string;
+    /** Additive (WP2): transport facts (`transport:<fact>`), only on the transport gateway. */
+    transport?: TransportFact[];
+}
+interface GatewayField extends Conditional {
+    path: string;
+    /** A category, or `"role"`: inherit the category of the input role the field is read from. */
+    category: Category | "role" | string;
+    level: CollectionLevel | string;
+    label: string;
+    /** Additive (WP2): capability that produces the field, `<key>@<version>`. */
+    via?: string;
+    /** Additive (WP2): parameters of the level (enum values, pattern, template, buckets, ...). */
+    transform?: Record<string, unknown>;
+    /** Additive (WP2): synthetic examples fitting the level. */
+    examples?: (string | number | boolean)[];
+    /** Additive (WP2): build switch the field depends on (absent in builds that turn it off). */
+    when?: string;
+    /** Additive (WP1): what an opaque-identifier field points to (credential, browser, session, tab, flow). */
+    pointsTo?: string;
+}
+/**
+ * A generated identifier (an output type, not a collection level).
+ * - `lifetime`: `"event"`, `"page-load"`, `"tab"`, `"persistent"` or an ISO 8601 duration (e.g. `"PT30M"` of
+ *   inactivity).
+ * - `exposedTo`: who besides Corbado can see it, e.g. `"corbado"`, `"page scripts (getSessionId)"`,
+ *   `"page scripts (local storage)"`.
+ */
+interface GeneratedEntry extends Conditional {
+    id: string;
+    category: Category | string;
+    pointsTo: string;
+    lifetime: string;
+    scope?: string;
+    exposedTo: string[];
+    /** Additive (WP2): plain-language label. */
+    label?: string;
+    /** Additive (WP2): build switch / config flag the entry depends on. */
+    when?: string;
+}
+/**
+ * Something the bundle writes to the browser.
+ * - `area`: `"local"`, `"session"`, `"cookie"`, `"indexeddb"`, `"opfs"`, `"web-locks"`, ...
+ * - `scope`: `"tab"`, `"origin"`, `"cookie domain + path"`.
+ * - `retention`: an ISO 8601 duration (enforced by code), `"tab"` (sessionStorage), `"PT0S"` (removed at once) or
+ *   `"persistent"`.
+ * - `owner`: `"sdk"`, `"project"`, `"third-party (<package>)"`.
+ * - `contents`: field and generated ids (typed references); `"sent:events"` = the whole queued event as sent.
+ * - `when` (see {@link Conditional}): without `otherwise` the entry is absent when `when` does not hold; with
+ *   `otherwise` the entry stays, merged with `otherwise` (e.g. a cache a build does not write but still removes).
+ */
+interface StoredEntry extends Conditional {
+    id: string;
+    area: string;
+    scope: string;
+    retention: string;
+    owner: string;
+    contents: string[];
+    /** Additive (WP2): the keys as written (`cbo_<name>_<projectId>`; `*` = the project id or a family). */
+    keys?: string[];
+    /** Additive (WP2): plain-language label. */
+    label?: string;
+    /** Additive (WP2): whether `retention` is enforced by code (purged), not only described. */
+    enforced?: boolean;
+    /** Additive (WP2): build switch / config flag the entry depends on. */
+    when?: string;
+    /**
+     * Additive (v2 descriptors): the bundle never writes the entry, it only removes it when found (keys of older
+     * versions). Such an entry keeps nothing (`contents` empty); its `retention` is `"PT0S"` for older tools.
+     */
+    deleteOnly?: boolean;
+    /** Additive (v2 descriptors): a plain-language remark shown with the entry. */
+    note?: string;
+    /** Additive (v2 descriptors): what the entry becomes when its `when` does not hold (merged over the entry). */
+    otherwise?: StoredVariant;
+}
+/** Additive (v2 descriptors): the fields of a {@link StoredEntry} that its `otherwise` variant may replace. */
+type StoredVariant = Partial<Pick<StoredEntry, "retention" | "enforced" | "contents" | "label" | "deleteOnly" | "note" | "keys">>;
+interface TelemetryEntry {
+    kind: string;
+    fields: string[];
+    /** Additive (WP2): plain-language label. */
+    label?: string;
+}
+/** Additive (WP2): what the transport sends besides the events (`transport:<fact>`). */
+interface TransportFact {
+    id: string;
+    label: string;
+    /** `"browser"` = added by the browser, not by the SDK. */
+    addedBy: "sdk" | "browser";
+    when?: string;
+}
+
+/**
+ * `ac:ceremony@1` (SDK part): the WebAuthn allowlist (`src/utils/webauthn-ceremony.ts`), used by the sanitizers in
+ * builds that define `__CBO_DATA_CEREMONY__ = true` (build switch `ceremony`). The library's credentials wrapper and
+ * its endpoint reductions are the callers (second entry point: WebAuthn payloads in request and response bodies).
+ * The side effects are the library's (`@corbado/autocapture` `src/readers/credentials.ts`): it wraps the two methods;
+ * the container proxy is used only where the runtime's server config allows it (`aap` = `"c1"`) and the methods
+ * themselves cannot be wrapped.
+ */
+declare const AC_CEREMONY: CapabilityDescriptor;
+
+/**
+ * Values the integration hands to the SDK's API that the SDK keeps in its own storage (referenced by
+ * `sdk:own-storage`). The full host contract (init options, page config) is gap G15 and follows with the library's
+ * host-config gateway.
+ */
+declare const SDK_API: GatewayDescriptor;
+
+/**
+ * Device gateway (`src/readers/device.ts`, collected by `src/device.ts`): fixed readers, no capability. Sent once
+ * per page with the first events (device info), together with the generated device handle and tab id (see
+ * the generated-ids gateway).
+ */
+declare const SDK_DEVICE: GatewayDescriptor;
+
+/**
+ * Generated-ids output gateway (`outputs.sent.generated`, gap G3). Rule (model 11e): technical if an id lives at most
+ * one tab or flow and never leaves the tab, otherwise opaque-identifier. Every id below is sent to Corbado, so all
+ * random ids are opaque-identifier. The sequence counters are not ids: they are technical fields of each record
+ * ({@link SDK_RECORD}).
+ */
+declare const SDK_GENERATED: GatewayDescriptor;
+/**
+ * Fields the SDK adds to every record it sends (decided 2026-11-08: the sequence counters are a technical field of
+ * the event, not a generated id). Source kind `record`: nothing is read from the page.
+ */
+declare const SDK_RECORD: GatewayDescriptor;
+
+/**
+ * Own-storage output gateway (`outputs.stored`, gap G2): every key the SDK writes. Keys are written as
+ * `cbo_<name>_<projectId>` (`*` below). `retention` is enforced by code where `enforced` is true: the outboxes and
+ * the email-link notes only in builds with `__CBO_DATA_RETENTION__` (build switch `retention`); without it the
+ * outboxes keep entries up to their caps (500 events, 1000 low events) and expired email-link notes stay until the
+ * next write. Contents reference field and generated ids; `sent:events` = whole queued records as they are sent.
+ *
+ * Not listed: the private-mode library's temporary test databases, test directory and `test` entry (removed at once,
+ * nothing kept on the device): a side effect of `sdk:private-mode@1`. Entries with `otherwise` stay in the manifest
+ * when their `when` does not hold, merged with the variant (contract `StoredEntry.otherwise`).
+ */
+declare const SDK_OWN_STORAGE: GatewayDescriptor;
+
+/**
+ * Page gateway (`src/readers/page.ts`), declared as it behaves today: the page path is sent raw (no templates yet,
+ * gap G8) with every batch's first event; query keys stay, their values are masked unless the config allowlists the
+ * key (`sourcePathQuery` / `sourcePathQueryAllow`). Templates, declared query reductions and the navigation entry
+ * follow with the G8 change.
+ */
+declare const SDK_PAGE: GatewayDescriptor;
+
+/**
+ * `sdk:input@1`: the input gateway (`src/readers/input.ts`, `src/readers/input-paste.ts`, collectors in
+ * `src/low-events/`), declared as it behaves today (v1). Inside the gateway it reads the field's LENGTH (and a
+ * checkbox's checked state) to tell typing, pasting, clearing and several-characters-at-once changes apart; neither
+ * the value nor the length leaves it. A value-free v2 comes later (model section 13, "Later").
+ * Side effect: the library's input reader (`@corbado/autocapture` `onInput`, `src/readers/inputs.ts`) watches the
+ * document for added fields; `ac:element@1` lists the same effect (same id) for element roles.
+ */
+declare const SDK_INPUT: CapabilityDescriptor;
+
+/**
+ * `sdk:password-managers@1`: password-manager detection (`src/readers/password-manager-extensions.ts`, sampled by
+ * `src/utils/password-manager-sampler.ts`). Compiled out with `__CBO_DATA_PMD__ = false` (build switch `pmd`).
+ */
+declare const SDK_PASSWORD_MANAGERS: CapabilityDescriptor;
+
+/**
+ * `sdk:private-mode@1`: private-mode detection (`src/readers/private-mode.ts`, the third-party library
+ * detectincognitojs). Compiled out with `__CBO_DATA_PRIVATE_MODE__ = false` (build switch `privateMode`).
+ * The library's temporary test databases, test directory and `test` storage entry are only this side effect: they
+ * are removed at once, so `sdk:own-storage` does not list them (nothing is kept on the device).
+ */
+declare const SDK_PRIVATE_MODE: CapabilityDescriptor;
+
+/**
+ * Transport output gateway (`src/transports/fetch.ts`, `src/readers/network.ts`): ingestion requests with fetch
+ * (keepalive, no credentials) and `sendBeacon` on page hide. Lists what leaves besides the events themselves.
+ */
+declare const SDK_TRANSPORT: GatewayDescriptor;
+
+/** `sdk:window@1`: the window gateway (`src/readers/window-events.ts`, `src/low-events/shared-window-observer.ts`). */
+declare const SDK_WINDOW: CapabilityDescriptor;
+
+/**
+ * `@corbado/observe/manifest`: collection manifest v2 descriptors of the SDK's gateways and capabilities, read by
+ * the autocapture tools from the package. Never imported by runtime code, so never part of a bundle.
+ */
+
+/** Every capability descriptor of this package. */
+declare const SDK_CAPABILITIES: readonly CapabilityDescriptor[];
+/** Every gateway descriptor of this package. */
+declare const SDK_GATEWAYS: readonly GatewayDescriptor[];
+/** WP1 names: the same lists. */
+declare const capabilities: CapabilityDescriptor[];
+declare const gateways: GatewayDescriptor[];
+
+export { AC_CEREMONY, CATEGORIES, CATEGORY_VALUE_LEVELS, type CapabilityDescriptor, type Category, type CollectionLevel, type Conditional, type GatewayDescriptor, type GatewayField, type GeneratedEntry, KIND_LADDERS, type ManifestId, NON_VALUE_LEVELS, type NonValueLevel, SDK_API, SDK_CAPABILITIES, SDK_DEVICE, SDK_GATEWAYS, SDK_GENERATED, SDK_INPUT, SDK_OWN_STORAGE, SDK_PAGE, SDK_PASSWORD_MANAGERS, SDK_PRIVATE_MODE, SDK_RECORD, SDK_TRANSPORT, SDK_WINDOW, type SideEffect, type SourceKind, type StoredEntry, type StoredVariant, type TelemetryEntry, type TransportFact, VALUE_LEVELS, type ValueLevel, capabilities, gateways };