ccp-core 0.4.0 → 0.5.1

package/dist/runtime.d.ts

@@ -1,4 +1,6 @@
-import { AuditStore, GrantStore, LimitStore, ManifestStore, PendingRequest, PendingStore, ReplayStore } from "./stores.js";
+import { type VerifiedManifest } from "./consumer.js";
+import { type AdmissionRequest, type AdmissionResult, type VerifiedIdentity, type VerifiedPolicy, type VerifyIdentityOptions } from "./identity.js";
+import { AuditStore, Grant, GrantStore, LimitStore, ManifestStore, PendingRequest, PendingStore, ReplayStore } from "./stores.js";
 import { utcnow } from "./time.js";
 export { utcnow };
 export interface Decision {
@@ -18,23 +20,80 @@ export declare class SchemaRegistry {
 }
 export type IntentExecutor = (params: any, access: HostAccess) => any;
 export type HostFunction = (...args: any[]) => any;
+export type HostClass = "read" | "write" | "disclose" | "control" | "compute";
+export type HostRisk = "read" | "write" | "disclose" | "irreversible";
+export type HostPlacement = "local" | "remote" | "delegated";
+export type ConfirmationFloor = "none" | "per_action";
+export type Idempotency = "pure" | "caller_key" | "atomic" | "none";
+/**
+ * A host contract (§26.4). Core hosts may omit it; every extension host must
+ * declare at least `class`, which fixes the risk and confirmation floor.
+ */
+export interface HostProfile {
+    class?: HostClass;
+    risk?: HostRisk;
+    minConfirmation?: ConfirmationFloor;
+    idempotency?: Idempotency;
+    /** May this host send data off the device? Defaults to false. */
+    network?: boolean;
+    /** Placements this host can serve. Defaults to `["local"]`. */
+    placement?: HostPlacement[];
+    /** Data categories this host may transmit. Defaults to none. */
+    fields?: string[];
+}
+export interface NormalizedHostProfile {
+    class: HostClass;
+    risk: HostRisk;
+    minConfirmation: ConfirmationFloor;
+    idempotency: Idempotency;
+    network: boolean;
+    placement: HostPlacement[];
+    fields: string[];
+}
+interface HostEntry {
+    fn: HostFunction;
+    profile: NormalizedHostProfile;
+}
+/** The only hosts that may be registered without an explicit profile. */
+export declare const CORE_HOSTS: ReadonlySet<string>;
+export declare class HostProfileError extends Error {
+    readonly code = "invalid_request";
+    constructor(message: string);
+}
+/**
+ * Validate and normalize a host profile (§26.4).
+ *
+ * Extension hosts (anything outside the core six) must declare a class; the
+ * rest of the contract follows from it unless explicitly overridden. A
+ * `write`, `control`, or `compute` host can never suppress confirmation, and
+ * an `irreversible` risk cannot either.
+ */
+export declare function validateHostProfile(name: string, profile?: HostProfile): NormalizedHostProfile;
+/** The grant's data-egress ceiling, enforced on every host call. */
+export interface EgressPolicy {
+    network: boolean;
+    fields: ReadonlySet<string>;
+}
 export declare class HostAccess {
     private readonly registry;
+    private readonly policy;
     private _granted;
-    constructor(registry: HostRegistry, granted: string[]);
+    constructor(registry: HostRegistry, granted: string[], policy?: EgressPolicy);
     call(name: string, ...args: any[]): any;
     has(name: string): boolean;
 }
 export declare class HostRegistry {
     private _hosts;
     private _intents;
-    registerHost(name: string, fn: HostFunction): void;
+    registerHost(name: string, fn: HostFunction, profile?: HostProfile): void;
     registerIntent(name: string, fn: IntentExecutor): void;
     host(name: string): HostFunction | undefined;
+    /** Metadata used to enforce placement, egress, and confirmation (§12). */
+    hostMeta(name: string): HostEntry | undefined;
     hasHost(name: string): boolean;
     intent(name: string): IntentExecutor | undefined;
     hasIntent(name: string): boolean;
-    access(granted: string[]): HostAccess;
+    access(granted: string[], policy?: EgressPolicy): HostAccess;
 }
 export interface RuntimeOptions {
     grants?: GrantStore;
@@ -46,7 +105,28 @@ export interface RuntimeOptions {
     hosts?: HostRegistry;
     audit?: AuditStore;
     clock?: () => string;
-    supportedCcp?: string;
+    supportedCcp?: string | readonly string[];
+}
+export interface AdmitRequestOptions {
+    policy: VerifiedPolicy;
+    request: AdmissionRequest;
+    /** Verified provider manifest that defines the admitted intent. */
+    manifest: VerifiedManifest | string;
+    confirmation?: Record<string, "none" | "per_action">;
+}
+export interface AdmitRequestResult {
+    result: AdmissionResult;
+    grant?: Grant;
+}
+/**
+ * Reserved suspension reason for a requester key change (§7.4). A grant
+ * suspended this way cannot be resumed; the consumer re-introduces the
+ * contact and creates a new grant.
+ */
+export declare const IDENTITY_CHANGED_REASON = "identity_changed";
+export interface VerifyContactOptions extends VerifyIdentityOptions {
+    /** Local contact the document is being verified for. */
+    contactId: string;
 }
 export declare class Runtime {
     readonly grants: GrantStore;
@@ -55,7 +135,7 @@ export declare class Runtime {
     readonly hosts: HostRegistry;
     readonly audit: AuditStore;
     readonly clock: () => string;
-    readonly supportedCcp: string;
+    readonly supportedCcp: string | readonly string[];
     readonly replay: ReplayStore;
     readonly limits: LimitStore;
     readonly pendingStore: PendingStore;
@@ -63,7 +143,78 @@ export declare class Runtime {
     submit(document: string, publicKey: Uint8Array): Promise<Decision>;
     confirm(pendingId: string, approved: boolean): Promise<Decision>;
     pending(pendingId: string): Promise<PendingRequest | undefined>;
+    /**
+     * Pause one grant (§9.4.1). Configuration, limits, and history are kept.
+     */
+    pauseGrant(id: string, reason?: string): Promise<Grant>;
+    /**
+     * Suspend one grant (§9.4.2). Used for security events such as a requester
+     * key change; resumption requires an explicit `resumeGrant`.
+     */
+    suspendGrant(id: string, reason?: string): Promise<Grant>;
+    /**
+     * Resume a paused or suspended grant (§9.4.3).
+     *
+     * Re-checks revocation, expiry, and the approved manifest before restoring
+     * authority. A revoked or expired grant cannot be resumed.
+     */
+    resumeGrant(id: string): Promise<Grant>;
+    /**
+     * Revoke one grant by id (§9.4.4). Permanent: the grant is not resumable and
+     * a new approval is required.
+     *
+     * Policy-created grants reuse their deterministic id, so revoking here also
+     * stops an admission rule from re-creating the same access (§25.8.3).
+     */
+    revokeGrant(id: string, reason?: string): Promise<Grant>;
+    /**
+     * Suspend every active grant bound to a contact (§7.4, §9.4.2).
+     * Returns the number of grants affected.
+     */
+    suspendContact(contactId: string, reason?: string): Promise<number>;
+    /**
+     * Verify an identity document for a known contact (§7.4, §25.8.4).
+     *
+     * On `identity_changed` — a valid signature from a different key — the
+     * contact's grants are suspended before the error is rethrown. A bad
+     * signature never suspends anything, so an attacker cannot force a
+     * suspension by sending garbage.
+     */
+    verifyContactIdentity(document: string, options: VerifyContactOptions): Promise<VerifiedIdentity>;
+    /**
+     * Admit a request under a reviewed policy (§25.8.3).
+     *
+     * `allow` creates or reuses the grant with the policy's deterministic id,
+     * records the admitting rule in the audit log, and leaves the request to
+     * proceed through `submit` normally. Revoked ids are consulted from the
+     * grant store, so a revocation is never undone here.
+     */
+    admitRequest(options: AdmitRequestOptions): Promise<AdmitRequestResult>;
+    /**
+     * Resolve the grant for this request.
+     *
+     * A requester may hold several grants over one manifest digest (for
+     * example, a manual grant and a policy-created one). The store lookup is
+     * the fast path; when it lands on a grant that does not enable the intent,
+     * prefer a grant that does. Revocation remains per grant (§25.8.3).
+     */
+    private resolveGrant;
+    private transition;
+    private setGrantState;
     private execute;
+    /**
+     * Enforce the grant's placement and egress ceilings before execution (§12).
+     * A host that needs network access cannot run under a grant that denies it.
+     */
+    private deploymentError;
+    /** True when a required host declares a per-action confirmation floor. */
+    private hostFloor;
+    private egressPolicy;
     private grantStateError;
+    /**
+     * Surface a recorded pause/suspend/revoke reason (§9.4.2). The reason is
+     * local and must not contain secrets; hosts choose what to record.
+     */
+    private stateDetail;
     private reject;
 }