@mdbase-dev/connect-protocol 0.1.0-beta.21

package/dist/index.d.ts

@@ -0,0 +1,756 @@
+export declare const CONTROL_PROTOCOL_VERSION: 1;
+export declare const ENCRYPTED_RELAY_PROTOCOL_VERSION: 1;
+export declare const LOOPBACK_PROTOCOL_VERSION: 1;
+export declare const DEFAULT_LOOPBACK_PORT: 28485;
+export declare const RELAY_ENCRYPTION_SUITE: "P256-HKDF-SHA256-AES256GCM";
+export declare const SYNC_PROTOCOL_VERSION: 1;
+export declare const CONTRACT_SETUP_CAPABILITY: "contract-setup-v1";
+export declare const RELAY_REQUIRED_CAPABILITIES: readonly ["authorization-activation", "encrypted-relay", "policy-ack"];
+export declare const RELAY_CAPABILITIES: readonly ["authorization-activation", "encrypted-relay", "policy-ack", "contract-setup-v1"];
+export declare const AUTHORITY_PROOF_VERSION: 1;
+export declare const AUTHORITY_PROOF_ALGORITHM: "P256-SHA256";
+export declare const AUTHORITY_PROOF_DOMAIN: "mdbase-authority-request-proof-v1";
+export declare const AUTHORITY_PROOF_HEADERS: {
+    readonly version: "x-mdbase-proof-version";
+    readonly timestamp: "x-mdbase-proof-timestamp";
+    readonly nonce: "x-mdbase-proof-nonce";
+    readonly signature: "x-mdbase-proof-signature";
+};
+/**
+ * Validate a native OAuth callback against the publisher of its web manifest.
+ * Reverse-domain private-use schemes keep native app identity tied to the
+ * manifest origin; PKCE remains mandatory at the authorization boundary.
+ */
+export declare function isNativeRedirectUri(url: URL, publisherHostname?: string): boolean;
+export declare const CONNECT_SCHEMA_IDS: {
+    readonly appManifest: "https://mdbase.dev/connect/schemas/mdbase-app.v1.json";
+    readonly notificationWebhook: "https://mdbase.dev/connect/schemas/notification-webhook.v1.json";
+    readonly dataContract: "https://mdbase.dev/schemas/v0.3/data-contract.schema.json";
+    readonly eventActionInterop: "https://mdbase.dev/schemas/interop/v0.1/profile.schema.json";
+    readonly protocol: "https://mdbase.dev/connect/schemas/connect-protocol.v1.json";
+    readonly encryptedRelay: "https://mdbase.dev/connect/schemas/encrypted-relay.v1.json";
+    readonly sync: "https://mdbase.dev/connect/schemas/sync.v1.json";
+};
+export type CollectionOperation = "describe" | "changes" | "read" | "query" | "list_views" | "execute_view" | "read_view_source" | "create_view_source" | "update_view_source" | "delete_view_source" | "validate" | "create" | "update" | "delete" | "rename" | "read_type" | "create_type" | "update_type" | "install_type_pack" | "list_timers" | "put_timer" | "cancel_timer" | "reconcile_timers" | "sync";
+export interface NotificationCriterion {
+    /** Stable, manifest-owned identifier selected by an installation. */
+    id: string;
+    /** Runtime event contract evaluated at the collection authority. */
+    event: ContractRequirement;
+    /** Canonical mdbase CEL. Event content never leaves the authority for evaluation. */
+    if?: {
+        $expr: string;
+    };
+    debounce?: string;
+    minimum_interval?: string;
+    /** Static Web Push copy. Dynamic record content is intentionally unsupported. */
+    presentation: {
+        title: string;
+        body?: string;
+        tag?: string;
+    };
+}
+export type NativeNotificationDelivery = {
+    /**
+     * Connect sends through FCM using revocable, least-privilege authority
+     * granted by the application's Firebase project.
+     */
+    mode: "managed_fcm";
+    firebase_project_id: string;
+} | {
+    /**
+     * Connect sends a signed, content-free signal to infrastructure operated
+     * by the application developer. That infrastructure owns APNs/FCM.
+     */
+    mode: "webhook";
+    url: string;
+};
+export interface ApplicationNotifications {
+    criteria: NotificationCriterion[];
+    /** Optional native delivery route. Web Push registration remains independent. */
+    native_delivery?: NativeNotificationDelivery;
+}
+/**
+ * The declaration bundled with an application build and registered inline.
+ *
+ * `id` is stable presentation metadata rather than proof of a publisher. Each
+ * exact declaration is independently identified and authorized by Connect.
+ */
+interface MdbaseAppManifestBase {
+    manifest_version: 1;
+    id: string;
+    name: string;
+    requirements?: ApplicationRequirements;
+    provisions?: ApplicationProvisions;
+    notifications?: ApplicationNotifications;
+}
+export interface MdbaseWebAppManifest extends MdbaseAppManifestBase {
+    /** Omitted by existing v1 declarations; explicit `web` is equivalent. */
+    distribution?: "web";
+    homepage: string;
+    icon?: string;
+    redirect_uris: string[];
+}
+export interface MdbasePortableAppManifest extends MdbaseAppManifestBase {
+    /**
+     * A downloaded, publisher-unverified application opened from a local file.
+     * Portable declarations use device authorization and never claim a web origin.
+     */
+    distribution: "portable";
+    /** Optional HTTPS page where the user can inspect the project or source. */
+    project_url?: string;
+    /** Optional HTTPS icon on the project URL's origin. */
+    icon?: string;
+}
+export type MdbaseAppManifest = MdbaseWebAppManifest | MdbasePortableAppManifest;
+export interface NotificationSignal {
+    /** Stable idempotency key generated by the collection authority. */
+    signal_id: string;
+    grant_id: string;
+    criterion_id: string;
+    /** Opaque authority cursor used by the app to retrieve current state after waking. */
+    cursor: string;
+}
+export interface NotificationPresentation {
+    title: string;
+    body?: string;
+    tag?: string;
+}
+export interface MdbaseNotification {
+    type: "mdbase.notification";
+    version: 1;
+    signal_id: string;
+    criterion_id: string;
+    cursor: string;
+    presentation: NotificationPresentation;
+}
+export interface NotificationWebhook {
+    type: "mdbase.notification.webhook";
+    version: 1;
+    delivery_id: string;
+    /** Opaque application grant reference returned during authorization. */
+    connection_id: string;
+    notification: MdbaseNotification;
+}
+export interface ContractRequirement {
+    id: string;
+    /** Exact semantic version of the collection-local mdbase data contract. */
+    version: string;
+}
+export interface ApplicationRequirements {
+    contracts: ContractRequirement[];
+    /** Access boundary requested after compatibility and provisioning checks. */
+    access?: "contract" | "full_collection";
+    /** Restrict authorization to durable provider-backed collections. */
+    collection_kind?: "hosted";
+}
+export interface TypePackManifestResource {
+    kind: "contract" | "type" | "schema";
+    source: string;
+    target: string;
+    digest: string;
+}
+export interface TypePackManifest {
+    kind: "mdbase.type-pack";
+    id: string;
+    version: string;
+    name?: string;
+    description?: string;
+    resources: TypePackManifestResource[];
+    [extension: `x-${string}`]: unknown;
+}
+export interface TypePackSourceResource {
+    source: string;
+    document: string;
+}
+export interface TypePackProvision {
+    /** Canonical type-pack manifest shown during approval and verified on install. */
+    manifest: TypePackManifest;
+    /** Exact UTF-8 resource bytes, keyed by each manifest source path. */
+    resources: TypePackSourceResource[];
+    /** Data contracts expected after the complete pack is installed. */
+    provides: ContractRequirement[];
+}
+export interface TypePackResourceDiff {
+    target: string;
+    kind: "contract" | "type" | "schema";
+    action: "create" | "replace" | "unchanged";
+    digest: string;
+}
+export interface TypePackInstallResult {
+    id: string;
+    version: string;
+    resources: TypePackResourceDiff[];
+    cleanup_deferred: boolean;
+}
+export interface ApplicationProvisions {
+    type_packs: TypePackProvision[];
+}
+export type ContractSetupChoice = {
+    contract: ContractRequirement;
+    mode: "starter";
+} | {
+    contract: ContractRequirement;
+    mode: "existing";
+    type_name: string;
+    /** Exact type source revision shown during approval. */
+    type_revision: string;
+    fields: Record<string, string>;
+    binding?: JsonObject;
+};
+export interface GrantScope {
+    /**
+     * Exact contract definitions and sorted implementation sets approved by the
+     * user. Digests make the scope fail closed if either the interface or any
+     * provider changes after approval.
+     */
+    contracts: CollectionContractDescriptor[];
+    access: "contract" | "full_collection";
+}
+export interface RelayOperationRequest {
+    type: "operation_request";
+    protocol_version: 1;
+    request_id: string;
+    grant_id: string;
+    collection_id: string;
+    application_id: string;
+    operation: CollectionOperation;
+    input: unknown;
+}
+export interface RelayOperationResponse {
+    type: "operation_response";
+    protocol_version: 1;
+    request_id: string;
+    ok: boolean;
+    result?: unknown;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface MdbaseOperationRequest<Input = unknown> {
+    protocol_version: 1;
+    request_id: string;
+    input: Input;
+}
+export type MdbaseOperationResponse<Result = unknown> = {
+    protocol_version: 1;
+    request_id: string;
+    ok: true;
+    result: Result;
+} | {
+    protocol_version: 1;
+    request_id: string;
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+};
+export interface GrantPolicy {
+    id: string;
+    application_id: string;
+    collection_id: string;
+    operations: CollectionOperation[];
+    scope: GrantScope;
+    application_name: string;
+    /** Distribution profile used when the exact application manifest was approved. */
+    application_distribution?: "web" | "portable";
+    application_homepage: string;
+    /** Informational HTTPS project page for a downloaded portable application. */
+    application_project_url?: string;
+    /** Exact browser origin authorized to use this grant over loopback. */
+    application_origin?: string;
+    application_icon?: string;
+    collection_name: string;
+    /** Approval-time criterion snapshot evaluated only by this collection authority. */
+    notification_criteria?: NotificationCriterion[];
+    created_at: string;
+    encryption?: GrantEncryption;
+}
+export interface GrantEncryption {
+    protocol_version: 1;
+    suite: typeof RELAY_ENCRYPTION_SUITE;
+    key_id: string;
+    scope_epoch: number;
+    connector_id: string;
+    collection_id: string;
+    application_agreement_public_key: string;
+    connector_agreement_public_key: string;
+}
+export interface EncryptedRelayEnvelope {
+    protocol_version: 1;
+    suite: typeof RELAY_ENCRYPTION_SUITE;
+    request_id: string;
+    grant_id: string;
+    application_id: string;
+    connector_id: string;
+    collection_id: string;
+    operation: CollectionOperation;
+    scope_epoch: number;
+    key_id: string;
+    counter: string;
+    ciphertext: string;
+}
+export interface SyncRecord<Frontmatter extends JsonObject = JsonObject> {
+    record_id: string;
+    path: string;
+    revision: string;
+    frontmatter: Frontmatter;
+    body: string;
+    types: string[];
+}
+export interface SyncCollectionResources {
+    revision: string;
+    spec_version: string;
+    types: CollectionTypeDescriptor[];
+    contracts: CollectionContractDescriptor[];
+    documents?: SyncResourceDocument[];
+}
+export interface SyncResourceDocument {
+    path: string;
+    kind: "configuration" | "type" | "contract" | "schema" | "view";
+    /** SHA-256 revision of the exact UTF-8 document (`sha256:<lowercase hex>`). */
+    revision: string;
+    document: string;
+}
+export interface AuthoritySnapshotRecord<Frontmatter extends JsonObject = JsonObject> {
+    record: SyncRecord<Frontmatter>;
+    document: string;
+}
+export interface AuthoritySnapshot<Frontmatter extends JsonObject = JsonObject> {
+    protocol_version: 1;
+    collection_id: string;
+    source_head: number;
+    source_revision: string;
+    manifest_digest: string;
+    resources: SyncCollectionResources;
+    records: Array<AuthoritySnapshotRecord<Frontmatter>>;
+}
+export interface AuthorityImportManifest {
+    protocol_version: 1;
+    collection_id: string;
+    source_head: number;
+    source_revision: string;
+    manifest_digest: string;
+    resources: SyncCollectionResources;
+    record_count: number;
+}
+export interface AuthorityImportRecord {
+    record_id: string;
+    path: string;
+    document: string;
+}
+export interface AuthorityImportSnapshot {
+    protocol_version: 1;
+    collection_id: string;
+    source_head: number;
+    source_revision: string;
+    manifest_digest: string;
+    resources: SyncCollectionResources;
+    records: AuthorityImportRecord[];
+}
+export interface AuthorityImportRecordPage {
+    protocol_version: 1;
+    page: number;
+    records: AuthorityImportRecord[];
+}
+export interface SyncSession {
+    protocol_version: 1;
+    session_id: string;
+    replica_id: string;
+    collection_id: string;
+    mode: "read_only" | "read_write";
+    scope_epoch: number;
+    retained_after: number;
+    head: number;
+    snapshot_id: string;
+    resources: SyncCollectionResources;
+}
+export interface SyncSnapshotPage<Frontmatter extends JsonObject = JsonObject> {
+    protocol_version: 1;
+    snapshot_id: string;
+    scope_epoch: number;
+    cursor: number;
+    records: Array<SyncSnapshotRecord<Frontmatter>>;
+    next_page?: string;
+}
+export interface SyncSnapshotRecord<Frontmatter extends JsonObject = JsonObject> extends SyncRecord<Frontmatter> {
+    /** Exact bytes whose SHA-256 revision and parsed metadata match this record. */
+    document: string;
+}
+export type SyncChange<Frontmatter extends JsonObject = JsonObject> = {
+    sequence: number;
+    type: "put";
+    record: SyncRecord<Frontmatter>;
+} | {
+    sequence: number;
+    type: "remove";
+    record_id: string;
+    previous_path: string;
+    revision: string;
+};
+export interface SyncChangesPage<Frontmatter extends JsonObject = JsonObject> {
+    protocol_version: 1;
+    scope_epoch: number;
+    events: Array<SyncChange<Frontmatter>>;
+    cursor: number;
+    head: number;
+    has_more: boolean;
+    reset_required: boolean;
+}
+export interface SyncMutation {
+    mutation_id: string;
+    replica_id: string;
+    scope_epoch: number;
+    operation: "create" | "update" | "rename" | "delete";
+    record_id: string;
+    base_revision?: string;
+    input: JsonObject;
+    created_at: string;
+    causal_predecessor?: string;
+}
+export interface SyncConflict<Frontmatter extends JsonObject = JsonObject> {
+    record_id: string;
+    mutation: SyncMutation;
+    current?: SyncRecord<Frontmatter>;
+    current_revision?: string;
+}
+export type SyncMutationReceipt<Frontmatter extends JsonObject = JsonObject> = {
+    mutation_id: string;
+    status: "applied" | "previously_applied";
+    sequence: number;
+    record?: SyncRecord<Frontmatter>;
+} | {
+    mutation_id: string;
+    status: "conflicted";
+    conflict: SyncConflict<Frontmatter>;
+} | {
+    mutation_id: string;
+    status: "rejected";
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export type EncryptedRelayOperationRequest = EncryptedRelayEnvelope & {
+    type: "encrypted_operation_request";
+};
+export type EncryptedRelayOperationResponse = EncryptedRelayEnvelope & {
+    type: "encrypted_operation_response";
+};
+export interface RelayPolicySnapshot {
+    type: "policy_snapshot";
+    protocol_version: 1;
+    request_id: string;
+    revision: string;
+    grants: GrantPolicy[];
+}
+export interface RelayHello {
+    type: "relay_hello";
+    protocol_version: 1;
+    connector_version: string;
+    capabilities: string[];
+}
+export interface RelayWelcome {
+    type: "relay_welcome";
+    protocol_version: 1;
+    session_id: string;
+    capabilities: string[];
+}
+export interface RelayIncompatible {
+    type: "relay_incompatible";
+    protocol_version: 1;
+    code: "connector_upgrade_required";
+    message: string;
+    update_url: string;
+}
+export interface RelayPolicyApplied {
+    type: "policy_applied";
+    protocol_version: 1;
+    request_id: string;
+    revision: string;
+    ok: boolean;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+export interface AuthorizationCollectionOffer {
+    collection_id: string;
+    display_name: string;
+    spec_version: string;
+    contracts: CollectionContractDescriptor[];
+    /** Minimal schema metadata; type source and collection paths never leave the authority. */
+    types: CollectionTypeDescriptor[];
+}
+export interface AuthorizationOfferResponse {
+    type: "authorization_offer_response";
+    protocol_version: 1;
+    request_id: string;
+    paused: boolean;
+    collections: AuthorizationCollectionOffer[];
+}
+export interface AuthorizationActivationResponse {
+    type: "authorization_activation_response";
+    protocol_version: 1;
+    request_id: string;
+    ok: boolean;
+    contracts: CollectionContractDescriptor[];
+    /** Exact setup plan applied by the authority. */
+    contract_setups: ContractSetupChoice[];
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+export interface ConnectorCollection {
+    id: string;
+    display_name: string;
+    spec_version: string;
+    enabled: boolean;
+    contracts: CollectionContractDescriptor[];
+}
+export type JsonObject = Record<string, unknown>;
+export interface MdbaseDiagnostic {
+    severity: "error" | "warning" | "info";
+    code: string;
+    message: string;
+    path?: string;
+    field?: string;
+    type?: string;
+    schema_location?: string;
+    details?: unknown;
+}
+export interface MdbaseOperationEnvelope<Result = JsonObject> {
+    valid: boolean;
+    result: Result;
+    diagnostics: MdbaseDiagnostic[];
+}
+export interface SavedViewPresentation extends JsonObject {
+    type: string;
+    fallback?: string;
+    mappings?: Record<string, string>;
+    options?: JsonObject;
+}
+export interface SavedViewSource {
+    path: string;
+    format: string;
+    revision: string;
+    writable: boolean;
+}
+export interface SavedNamedView {
+    id: string;
+    name: string;
+    properties: SavedViewProperty[];
+    presentation?: SavedViewPresentation;
+}
+export interface SavedViewProperty {
+    key: string;
+    label?: string;
+    description?: string;
+    format?: string;
+    hidden?: boolean;
+}
+export interface SavedViewDocument {
+    id: string;
+    name: string;
+    source: SavedViewSource;
+    views: SavedNamedView[];
+}
+export interface SavedViewList {
+    views: SavedViewDocument[];
+    meta: {
+        total_count: number;
+    };
+}
+export interface SavedViewSourceDocument {
+    path: string;
+    format: string;
+    revision: string;
+    document: string;
+}
+export interface ReadViewSourceInput {
+    path: string;
+}
+export interface CreateViewSourceInput {
+    document: string;
+    path?: string;
+    format?: string;
+    name?: string;
+}
+export interface UpdateViewSourceInput {
+    path: string;
+    document: string;
+    if_revision?: string;
+}
+export interface DeleteViewSourceInput {
+    path: string;
+    if_revision?: string;
+}
+export interface DeleteViewSourceResult {
+    path: string;
+    deleted: boolean;
+}
+export interface ExecuteViewInput {
+    path: string;
+    view: string;
+    context?: {
+        path: string;
+    } | null;
+    limit?: number;
+    offset?: number;
+    render?: boolean;
+}
+/**
+ * A saved-view row always includes the canonical frontmatter used to evaluate
+ * the view. Empty-frontmatter Markdown is represented by an empty object.
+ */
+export interface SavedViewRecord<Frontmatter extends JsonObject = JsonObject> extends Omit<QueryRecord<Frontmatter>, "effective_frontmatter"> {
+    effective_frontmatter: Frontmatter;
+    values?: JsonObject;
+}
+export interface SavedViewExecution<Frontmatter extends JsonObject = JsonObject> {
+    results: Array<SavedViewRecord<Frontmatter>>;
+    meta: {
+        total_count: number;
+        has_more: boolean;
+        view: {
+            path: string;
+            id: string;
+        };
+        context?: {
+            path: string;
+        };
+        groups?: Array<{
+            values: JsonObject;
+            count: number;
+            summaries: JsonObject;
+        }>;
+    };
+}
+export interface CollectionFileMetadata extends JsonObject {
+    name: string;
+    folder: string;
+    size: number;
+    mtime: string;
+    tags?: string[];
+    links?: unknown[];
+    embeds?: unknown[];
+}
+export interface DataContractViewIdentity {
+    id: string;
+    version: string;
+    digest: string;
+    type: string;
+    implementation_digest: string;
+}
+/**
+ * A projected query row. Frontmatter members are optional because
+ * `frontmatter_mode` selects which fixed-semantics representation is returned.
+ */
+export interface QueryRecord<Frontmatter extends JsonObject = JsonObject> {
+    path: string;
+    frontmatter?: Frontmatter;
+    effective_frontmatter?: Frontmatter;
+    body?: string;
+    types: string[];
+    file: Partial<CollectionFileMetadata> & {
+        path?: string;
+    };
+    /** Present when the authority returned a normalized contract projection. */
+    contract?: DataContractViewIdentity;
+}
+/** An authoritative record or a field-limited data-contract projection. */
+export interface RecordDocument<Frontmatter extends JsonObject = JsonObject> {
+    path: string;
+    revision: string;
+    types: string[];
+    frontmatter: Frontmatter;
+    effective_frontmatter: Frontmatter;
+    /** Omitted from contract-scoped results. */
+    body?: string;
+    /**
+     * The exact UTF-8 Markdown source, including frontmatter delimiters,
+     * comments, quoting, whitespace, line endings, and trailing newline.
+     * Returned only when the operation requests it.
+     */
+    document?: string;
+    file: Partial<CollectionFileMetadata> & {
+        path?: string;
+    };
+    /** Present when the authority returned a normalized contract projection. */
+    contract?: DataContractViewIdentity;
+}
+export interface CollectionTypeDescriptor {
+    name: string;
+    version?: number;
+    description?: string;
+    /** Digest of the exact type source used as a setup precondition. */
+    revision?: string;
+    /** Collection-relative source path. */
+    path?: string;
+    /** Complete portable type frontmatter, including extension declarations. */
+    definition?: JsonObject;
+    schema: JsonObject;
+    collection?: JsonObject;
+    lifecycle?: JsonObject;
+    extensions: Record<string, unknown>;
+}
+export interface CollectionTypeDocument {
+    name: string;
+    path: string;
+    revision: string;
+    document: string;
+}
+export interface CollectionContractDescriptor {
+    /** Collection operations expose only record contracts. */
+    contract_type: "record";
+    id: string;
+    version: string;
+    /** Digest of the resolved contract schemas and metadata. */
+    digest: string;
+    /** Resolved portable record-view schema. */
+    schema: JsonObject;
+    /** Resolved implementation-binding schema, when the contract declares one. */
+    binding_schema?: JsonObject;
+    /** Every type currently implementing this exact contract, sorted by type name. */
+    implementations: CollectionContractImplementationDescriptor[];
+}
+export interface CollectionContractImplementationDescriptor {
+    type_name: string;
+    type_version: number;
+    type_path?: string;
+    /** Digest of the contract digest, type schema, fields, and binding. */
+    digest: string;
+    fields: Record<string, string>;
+    binding?: JsonObject;
+}
+export interface CollectionDescription {
+    protocol_version: 1;
+    collection_id: string;
+    display_name: string;
+    spec_version: string;
+    operations: CollectionOperation[];
+    change_cursor: number;
+    types: CollectionTypeDescriptor[];
+    contracts: CollectionContractDescriptor[];
+    /** Canonical collection settings; extension and implementation-specific values are omitted. */
+    configuration?: JsonObject;
+}
+export interface CollectionChange {
+    cursor: number;
+    type: string;
+    occurred_at: string;
+    payload: JsonObject;
+}
+export interface CollectionChangesPage {
+    events: CollectionChange[];
+    cursor: number;
+    has_more: boolean;
+    reset: boolean;
+}
+export {};