permdock 0.6.0 → 0.8.0

package/dist/index-BhxEUY9J.d.ts

@@ -0,0 +1,233 @@
+import { T as Policy, sr as Principal, ut as TokenSigner } from "./policy-types-CCiDRZBH.js";
+import { E as SsfPermDockOptions, O as SsfStreamConfiguration, T as SsfPermDock, _ as SetSubject, c as PushSetOptions, d as SetDelivery, g as SetQueue, h as SetPollHandlerOptions, k as SsfStreamStatus, m as SetEvent, p as SetError, t as CaepCommon, v as SignSetOptions } from "./types-DjuMBNF9.js";
+//#region src/ssf/create.d.ts
+declare function createPermDock<TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, options: SsfPermDockOptions): SsfPermDock;
+//#endregion
+//#region src/ssf/poll-client.d.ts
+type PollSetsOptions = {
+  /**
+   * The transmitter's RFC 8936 poll endpoint, the stream's
+   * `delivery.endpoint_url`.
+   */
+  readonly endpoint: string;
+  /** The `Authorization` header value. */
+  readonly authorization?: string;
+  /** `jti` values of SETs the receiver accepted. */
+  readonly acks?: readonly string[];
+  /** SETs the receiver refused, by `jti`. */
+  readonly setErrs?: Readonly<Record<string, SetError>>;
+  /** At most this many SETs in the response; default 100. `0` only acknowledges. */
+  readonly maxEvents?: number;
+  /** Default `true`: answer at once rather than wait for a SET. */
+  readonly returnImmediately?: boolean;
+  readonly fetch?: typeof fetch;
+  readonly signal?: AbortSignal;
+};
+/**
+ * One SET from a poll response: its `jti` and the compact JWS, not yet
+ * verified.
+ */
+type PolledSet = {
+  readonly jti: string;
+  readonly set: string;
+};
+type PollSetsResult = {
+  readonly ok: true;
+  readonly sets: readonly PolledSet[];
+  readonly moreAvailable: boolean;
+} | Extract<SetDelivery, {
+  readonly ok: false;
+}>;
+/**
+ * One RFC 8936 poll request: sends `acks` and `setErrs` and answers the SETs
+ * the transmitter returns, unverified. A failure maps as `pushSet`'s does; a
+ * `2xx` body without a `sets` object is `invalid-request`. Never throws.
+ */
+declare function pollSets(options: PollSetsOptions): Promise<PollSetsResult>;
+//#endregion
+//#region src/ssf/set-queue.d.ts
+/**
+ * An in-process `SetQueue`: pending SETs per stream in insertion order. A
+ * process restart loses them; a deployment with more than one instance needs a
+ * shared queue.
+ */
+declare function memorySetQueue(): SetQueue;
+/**
+ * The RFC 8936 poll endpoint over a `SetQueue`. It applies the request's `acks`
+ * and `setErrs`, then answers `{ sets, moreAvailable }` with up to `maxEvents`
+ * pending SETs. It answers at once whatever `returnImmediately` says, which RFC
+ * 8936 section 2.4 allows.
+ */
+declare function setPollHandler(options: SetPollHandlerOptions): (request: Request) => Promise<Response>;
+//#endregion
+//#region src/ssf/streams.d.ts
+/** One stream a transmitter holds and the receiver that created it. */
+type SsfStream = {
+  /**
+   * The receiver `ssfTransmitter`'s `authorize` answered when the stream was
+   * created.
+   */
+  readonly owner: string;
+  readonly configuration: SsfStreamConfiguration;
+};
+/**
+ * The streams an SSF 1.0 transmitter serves (section 8.1). A new stream is
+ * `enabled`; `status` answers `null` for a stream that does not exist.
+ */
+type SsfStreamStore = {
+  /** Names the implementation in errors and events. */
+  readonly name?: string;
+  create: (owner: string, configuration: SsfStreamConfiguration) => void | Promise<void>;
+  get: (streamId: string) => SsfStream | null | Promise<SsfStream | null>;
+  /**
+   * Every stream of `owner`, or every stream when `owner` is absent, oldest
+   * first.
+   */
+  list: (owner?: string) => readonly SsfStream[] | Promise<readonly SsfStream[]>;
+  /**
+   * Replaces the configuration of the stream `configuration.stream_id`; the
+   * owner and status stay.
+   */
+  update: (configuration: SsfStreamConfiguration) => void | Promise<void>;
+  delete: (streamId: string) => void | Promise<void>;
+  status: (streamId: string) => SsfStreamStatus | null | Promise<SsfStreamStatus | null>;
+  setStatus: (status: SsfStreamStatus) => void | Promise<void>;
+};
+/**
+ * An in-process `SsfStreamStore`. A process restart loses every stream; a
+ * deployment with more than one instance needs a shared store.
+ */
+declare function memorySsfStreamStore(): SsfStreamStore;
+//#endregion
+//#region src/ssf/transmitter-handler.d.ts
+type SsfTransmitterOptions = {
+  /** `iss` of every stream and of the metadata; the `iss` the signer writes. */
+  readonly issuer: string;
+  /**
+   * The URL the handler is mounted at; endpoints are `<endpoint>/stream`,
+   * `/status`, `/verify` and `/poll`. Default `issuer`.
+   */
+  readonly endpoint?: string;
+  readonly streams: SsfStreamStore;
+  readonly queue: SetQueue;
+  readonly signer: TokenSigner;
+  /**
+   * The receiver the request's credentials authenticate, or `null` to refuse it
+   * with `401`.
+   */
+  readonly authorize: (request: Request) => string | null | Promise<string | null>;
+  /** `aud` of a receiver's streams; default the receiver itself. */
+  readonly audience?: (receiver: string) => string | readonly string[];
+  readonly jwksUri?: string;
+  /** Default every CAEP and RISC event PermDock's receiver handles. */
+  readonly eventsSupported?: readonly string[];
+  /** The largest `maxEvents` a poll is answered with; default 100. */
+  readonly maxEvents?: number;
+  readonly fetch?: typeof fetch;
+};
+type FanOutSetOptions = {
+  readonly streams: SsfStreamStore;
+  readonly queue: SetQueue;
+  readonly signer: TokenSigner;
+  readonly fetch?: typeof fetch;
+};
+/**
+ * How one stream took a SET. `queued` is `true` for a poll stream and for a
+ * paused push stream.
+ */
+type SsfFanOut = {
+  readonly stream: string;
+  readonly jti: string;
+  readonly queued: boolean;
+  readonly delivery: SetDelivery;
+};
+/**
+ * Signs `event` once per distinct stream audience and delivers it to every
+ * stream that is not disabled and has the event in `events_delivered`: a push
+ * stream through `pushSet`, a poll stream or a paused stream into the queue.
+ * Answers one row per stream that took the event.
+ */
+declare function fanOutSet(event: SetEvent, options: FanOutSetOptions): Promise<readonly SsfFanOut[]>;
+/**
+ * An SSF 1.0 transmitter as one Fetch handler, routed by path suffix:
+ * `/.well-known/ssf-configuration` (section 7.1), `/stream` (8.1.1), `/status`
+ * (8.1.2), `/verify` (8.1.4) and `/poll` (RFC 8936). Each receiver sees only
+ * the streams it created. Disabling or deleting a stream drops its pending
+ * SETs; a paused stream holds them until it is enabled again.
+ */
+declare function ssfTransmitter(options: SsfTransmitterOptions): (request: Request) => Promise<Response>;
+//#endregion
+//#region src/ssf/transmitter.d.ts
+/** SSF 1.0 delivery method URN for RFC 8935 push. */
+declare const SSF_PUSH_DELIVERY = "urn:ietf:rfc:8935";
+/** SSF 1.0 delivery method URN for RFC 8936 poll. */
+declare const SSF_POLL_DELIVERY = "urn:ietf:rfc:8936";
+/**
+ * Signs one event as an RFC 8417 Security Event Token (`typ: secevent+jwt`):
+ * `sub_id` is the event's subject and `events` holds exactly one entry, as SSF
+ * 1.0 requires. `iss` is the signer's own.
+ */
+declare function signSet(event: SetEvent, signer: TokenSigner, options: SignSetOptions): Promise<string>;
+/**
+ * Pushes one SET to a receiver (RFC 8935). A `2xx` is delivery; a `400` maps
+ * the receiver's `err` to a cause; `401` and `403` are `authentication-failed`
+ * and `access-denied`; a network failure, a timeout, a `429` or a `5xx` is
+ * `unavailable` with `retry: true`. Never throws.
+ */
+declare function pushSet(set: string, options: PushSetOptions): Promise<SetDelivery>;
+type CaepCredentialChange = CaepCommon & {
+  readonly credentialType: string;
+  readonly changeType: "create" | "revoke" | "update" | "delete";
+  readonly friendlyName?: string;
+  readonly x509Issuer?: string;
+  readonly x509Serial?: string;
+  readonly fido2Aaguid?: string;
+};
+type CaepTokenClaimsChange = CaepCommon & {
+  readonly claims: Readonly<Record<string, unknown>>;
+};
+type CaepAssuranceLevelChange = CaepCommon & {
+  readonly namespace: string;
+  readonly currentLevel: string;
+  readonly previousLevel?: string;
+  readonly changeDirection?: "increase" | "decrease";
+};
+type CaepDeviceComplianceChange = CaepCommon & {
+  readonly previousStatus: "compliant" | "not-compliant";
+  readonly currentStatus: "compliant" | "not-compliant";
+};
+type CaepEvents = {
+  readonly sessionRevoked: (input: CaepCommon) => SetEvent;
+  readonly credentialChange: (input: CaepCredentialChange) => SetEvent;
+  readonly tokenClaimsChange: (input: CaepTokenClaimsChange) => SetEvent;
+  readonly assuranceLevelChange: (input: CaepAssuranceLevelChange) => SetEvent;
+  readonly deviceComplianceChange: (input: CaepDeviceComplianceChange) => SetEvent;
+};
+/** CAEP 1.0 event builders; each returns a `SetEvent` for `signSet`. */
+declare const caepEvents: CaepEvents;
+type RiscAccountDisabled = {
+  readonly subject: SetSubject;
+  readonly reason?: "hijacking" | "bulk-account";
+};
+type RiscCredentialCompromise = CaepCommon & {
+  readonly credentialType: string;
+};
+type RiscEvents = {
+  readonly accountDisabled: (input: RiscAccountDisabled) => SetEvent;
+  readonly accountPurged: (input: {
+    readonly subject: SetSubject;
+  }) => SetEvent;
+  readonly credentialCompromise: (input: RiscCredentialCompromise) => SetEvent;
+};
+/**
+ * RISC 1.0 event builders for the events PermDock's receiver treats as revoking
+ * every session.
+ */
+declare const riscEvents: RiscEvents;
+/**
+ * The SSF 1.0 section 8.1.4 verification event for `stream`, echoing the
+ * receiver's `state`. Its subject is the stream, never a principal.
+ */
+declare function streamVerificationEvent(stream: string, state?: string): SetEvent;
+//#endregion
+export { createPermDock as A, memorySsfStreamStore as C, PollSetsResult as D, PollSetsOptions as E, PolledSet as O, SsfStreamStore as S, setPollHandler as T, SsfFanOut as _, CaepTokenClaimsChange as a, ssfTransmitter as b, RiscEvents as c, caepEvents as d, pushSet as f, FanOutSetOptions as g, streamVerificationEvent as h, CaepEvents as i, pollSets as k, SSF_POLL_DELIVERY as l, signSet as m, CaepCredentialChange as n, RiscAccountDisabled as o, riscEvents as p, CaepDeviceComplianceChange as r, RiscCredentialCompromise as s, CaepAssuranceLevelChange as t, SSF_PUSH_DELIVERY as u, SsfTransmitterOptions as v, memorySetQueue as w, SsfStream as x, fanOutSet as y };

package/dist/index-Bv5iXPqU.d.ts

@@ -0,0 +1,210 @@
+import { T as Policy, j as PolicyVocabulary, q as DecisionSink, sr as Principal, tn as DeliveryChannel } from "./policy-types-CCiDRZBH.js";
+import { u as Permission } from "./permission-types-CAY-GU7e.js";
+import { t as Operation } from "./operations-Ci_rT6Uo.js";
+import { _ as PrincipalSource, a as PermDock } from "./permdock-B6Sf4T_S.js";
+import { t as JsonSchemaNode } from "./json-schema-BfXgnRNT.js";
+import { _ as TransportOptions, a as DeliveryReport, c as DeliveryTransport, g as TransportMessages, i as DeliveryMessages, l as DeliveryTransports, m as Recipient, o as DeliveryResult, r as DeliverOptions, s as DeliveryTarget, y as WebhookTransport } from "./types-yUuPR5Hy.js";
+import { l as WebhookSigner } from "./standard-webhooks-C-qX4mJW.js";
+//#region src/delivery/audience.d.ts
+type Audience = {
+  /**
+   * Principal ids `decideFor` grants, in discovery or candidate order, each
+   * once.
+   */
+  readonly principals: readonly string[];
+  /**
+   * `false` when `whoCan` could not list every holder: someone granted may be
+   * missing.
+   */
+  readonly complete: boolean;
+};
+type AudienceOptions = {
+  /** Check only these principals instead of listing holders with `whoCan`. */
+  readonly candidates?: readonly string[];
+};
+/**
+ * Who may receive a delivery about `row`: the holders `whoCan` lists (or
+ * `candidates`), kept only where `decideFor` grants `permission` in the
+ * sender's active tenant. A collection permission has no holders to list, so it
+ * needs `candidates`; without them it is empty and incomplete.
+ */
+declare function audience(permdock: PermDock, permission: Permission, row: unknown, options?: AudienceOptions): Promise<Audience>;
+/** One event a subscriber may receive: the permission its row needs. */
+type SubscriberEvent = {
+  readonly permission: Permission;
+  readonly row?: unknown;
+};
+/**
+ * The subscribers whose principal `decideFor` grants the event's permission on
+ * its row, in their order: the per-event filter for webhook endpoints and
+ * realtime channels. A subscriber without a string `principal` is dropped.
+ */
+declare function subscribersFor<S extends {
+  readonly principal: string;
+}>(permdock: PermDock, event: SubscriberEvent, subscribers: readonly S[]): Promise<S[]>;
+//#endregion
+//#region src/delivery/connector.d.ts
+type Https = `https://${string}`;
+type ConnectorBase<K extends string, C> = {
+  readonly id?: string;
+  readonly kind: K;
+  readonly name: string;
+  readonly config: C;
+};
+type SiemDestination = "splunk-hec" | "sentinel" | "security-lake" | "google-secops" | "elastic" | "datadog";
+/**
+ * A connector body in wire format v1 (`schemas/connector-v1.json`), one member
+ * per kind.
+ */
+type Connector = ConnectorBase<"webhook", {
+  readonly url: Https;
+  readonly types?: readonly string[];
+}> | ConnectorBase<"otlp", {
+  readonly endpoint: Https;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly signals?: readonly ("logs" | "traces")[];
+}> | ConnectorBase<"siem", {
+  readonly destination: SiemDestination;
+  readonly endpoint: Https;
+  readonly headers?: Readonly<Record<string, string>>;
+}> | ConnectorBase<"evidence", {
+  readonly format: "jws" | "ocsf" | "csv";
+  readonly destination: Https;
+  readonly schedule?: "hourly" | "daily";
+}> | ConnectorBase<"scim", {
+  readonly tenant: string;
+  readonly target: Https;
+  readonly groupRoles?: Readonly<Record<string, string>>;
+}> | ConnectorBase<"caep-transmitter", {
+  readonly issuer: Https;
+  readonly jwks_uri?: Https;
+  readonly delivery: "push" | "poll";
+  readonly poll_endpoint?: Https;
+}> | ConnectorBase<"federated-upstream", {
+  readonly discovery: Https;
+  readonly client_id: string;
+  readonly scopes?: readonly string[];
+}> | ConnectorBase<"chat", {
+  readonly platform: "slack" | "teams";
+  readonly workspace: string;
+}> | ConnectorBase<"email", {
+  readonly from: string;
+}> | ConnectorBase<"vercel-oidc", {
+  readonly team_id: string;
+  readonly project_id?: string;
+  readonly environment?: "production" | "preview" | "development";
+}>;
+type ConnectorKind = Connector["kind"];
+/**
+ * One problem with a connector body; `path` is an RFC 6901 JSON pointer into
+ * it.
+ */
+type ConnectorIssue = {
+  readonly path: string;
+  readonly message: string;
+};
+type ParseConnectorResult = {
+  readonly ok: true;
+  readonly connector: Connector;
+} | {
+  readonly ok: false;
+  readonly issues: readonly ConnectorIssue[];
+};
+/** The kinds `connector-v1` lists, in schema order. */
+declare const CONNECTOR_KINDS: readonly ConnectorKind[];
+/**
+ * Checks `input` against `connector-v1.json` and answers a frozen copy, or
+ * every issue with a JSON pointer. The branch is chosen by `kind`, so an issue
+ * names the field rather than "no branch matched".
+ */
+declare function parseConnector(input: unknown): ParseConnectorResult;
+//#endregion
+//#region src/delivery/connector-schema.d.ts
+/**
+ * `schemas/connector-v1.json`: the body of a PermDock Cloud connector, one
+ * `oneOf` branch per kind with a closed `config`. Only the `otlp` and `siem`
+ * `headers` maps hold a secret; a store seals their values and lists names
+ * only.
+ */
+declare const CONNECTOR_SCHEMA: JsonSchemaNode;
+//#endregion
+//#region src/delivery/memory-transport.d.ts
+type MemoryDelivery<C extends DeliveryChannel> = {
+  readonly target: DeliveryTarget<C>;
+  readonly message: TransportMessages[C];
+  readonly options: TransportOptions;
+};
+type MemoryDeliveryTransport<C extends DeliveryChannel> = DeliveryTransport<C> & {
+  /** Every delivery `respond` answered `sent` for, oldest first. */
+  readonly deliveries: readonly MemoryDelivery<C>[];
+};
+type MemoryDeliveryTransportOptions<C extends DeliveryChannel> = {
+  /**
+   * The result per delivery; defaults to `sent`. A throw propagates, as from a
+   * provider client.
+   */
+  readonly respond?: (target: DeliveryTarget<C>, message: TransportMessages[C]) => DeliveryResult;
+};
+/**
+ * An in-process transport for tests and examples: it records what it would have
+ * sent.
+ */
+declare function memoryDeliveryTransport<C extends DeliveryChannel>(channel: C, options?: MemoryDeliveryTransportOptions<C>): MemoryDeliveryTransport<C>;
+//#endregion
+//#region src/delivery/router.d.ts
+type DeliveryPermDockOptions = {
+  readonly transports: DeliveryTransports;
+  /** Resolves `{ address }` recipients through `principalByIdentity`. */
+  readonly principals?: PrincipalSource;
+  /** Receives one `delivery` event per recipient. A throw is ignored. */
+  readonly sink?: DecisionSink;
+  /** The `from` of an email whose message sets none. */
+  readonly from?: string;
+  /** The event `source`; defaults to `permdock`. */
+  readonly source?: string;
+};
+type DeliveryPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
+  /**
+   * Checks every recipient against `target`'s permission on `row` with
+   * `permdock.decideFor`, routes the granted ones to the transport of their
+   * channel, and writes one `delivery` event per recipient. Never rejects: a
+   * refused recipient or a transport error is a `failed` event.
+   */
+  readonly deliver: (permdock: PermDock<V>, target: Permission | Pick<Operation, "name" | "permission">, row: unknown, recipients: readonly Recipient[], messages: Partial<DeliveryMessages>, options?: DeliverOptions) => Promise<DeliveryReport>;
+};
+/**
+ * Routes checked recipients to channel transports and records a delivery event
+ * for each.
+ */
+declare function createPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(_policy: Policy<TUser, TPrincipal, V>, options: DeliveryPermDockOptions): DeliveryPermDock<V>;
+//#endregion
+//#region src/delivery/target.d.ts
+/**
+ * Whether `value` is a target the router checked for `channel`: a non-empty
+ * address and a granted decision. A transport calls it first and refuses
+ * anything else, so a hand-built recipient never reaches a provider.
+ */
+declare function isDeliveryTarget<C extends DeliveryChannel>(value: unknown, channel: C): value is DeliveryTarget<C>;
+/**
+ * An RFC 5322 `addr-spec` in dot-atom form with a DNS domain, at most 254
+ * characters (RFC 5321 path limit). Quoted local parts, comments and domain
+ * literals are refused.
+ */
+declare function isAddrSpec(value: string): boolean;
+//#endregion
+//#region src/delivery/webhook-transport.d.ts
+type WebhookTransportOptions = {
+  /** Defaults to the global `fetch`. */
+  readonly fetch?: typeof fetch;
+  /** Milliseconds before a request is aborted as `unavailable`. Defaults to 10000. */
+  readonly timeout?: number;
+};
+/**
+ * Posts each CloudEvent to the target's https endpoint as
+ * `application/cloudevents+json`, signed with the Standard Webhooks headers.
+ * `webhook-id` is the idempotency key, so a retry repeats it and the receiver
+ * drops the duplicate. Redirects are not followed.
+ */
+declare function webhookTransport(signer: WebhookSigner, options?: WebhookTransportOptions): WebhookTransport;
+//#endregion
+export { audience as C, SubscriberEvent as S, ParseConnectorResult as _, DeliveryPermDock as a, Audience as b, MemoryDelivery as c, memoryDeliveryTransport as d, CONNECTOR_SCHEMA as f, ConnectorKind as g, ConnectorIssue as h, isDeliveryTarget as i, MemoryDeliveryTransport as l, Connector as m, webhookTransport as n, DeliveryPermDockOptions as o, CONNECTOR_KINDS as p, isAddrSpec as r, createPermDock as s, WebhookTransportOptions as t, MemoryDeliveryTransportOptions as u, SiemDestination as v, subscribersFor as w, AudienceOptions as x, parseConnector as y };