permdock 0.4.0 → 0.6.0

package/dist/{index-BwMe94Xq.d.ts → index-Ch8LpNDp.d.ts}

@@ -1,5 +1,7 @@
-import { W as DecisionSink, Z as MembershipSource, ut as TokenVerifier } from "./policy-types-sp9P1iIV.js";
-import { n as RevocationFeed } from "./revocations-Cy06JNx2.js";
+import { dt as TokenVerifier, et as MembershipSource, q as DecisionSink } from "./policy-types-n0uRTsW8.js";
+import { V as AppData } from "./vocabulary-CN8H_9UF.js";
+import { n as RevocationFeed } from "./revocations-R07lFBnX.js";
+import { t as ClaimsMap } from "./claims-map-Ca-QX8C6.js";
 //#region src/scim/types.d.ts
 declare const SCIM_CONTENT_TYPE = "application/scim+json";
 declare const USER_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:User";
@@ -7,7 +9,10 @@ declare const GROUP_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:Group";
 declare const LIST_SCHEMA = "urn:ietf:params:scim:api:messages:2.0:ListResponse";
 declare const ERROR_SCHEMA = "urn:ietf:params:scim:api:messages:2.0:Error";
 declare const PATCH_SCHEMA = "urn:ietf:params:scim:api:messages:2.0:PatchOp";
-declare const ROLES_EXTENSION = "urn:permdock:scim:schemas:extension:roles:1.0";
+/** The RFC 7643 section 3.3 Group extension that carries PermDock roles. */
+declare const ROLES_EXTENSION = "urn:ietf:params:scim:schemas:extension:permdock:2.0:Group";
+/** The extension that carries the application's own data (`x`) on a User or a Group. */
+declare const APP_DATA_EXTENSION = "urn:ietf:params:scim:schemas:extension:permdock:2.0:AppData";
 type DirectoryMeta = {
   readonly created: string;
   readonly lastModified: string;
@@ -25,6 +30,8 @@ type DirectoryUser = {
   readonly userName: string;
   readonly active: boolean;
   readonly emails?: readonly DirectoryEmail[];
+  /** The application's own data, from the `AppData` extension; plain JSON, never read by a decision. */
+  readonly x?: AppData;
   readonly meta: DirectoryMeta;
 };
 type DirectoryGroupMember = {
@@ -36,6 +43,8 @@ type DirectoryGroup = {
   readonly displayName: string;
   readonly members: readonly DirectoryGroupMember[];
   readonly roles?: readonly string[];
+  /** The application's own data, from the `AppData` extension; plain JSON, never read by a decision. */
+  readonly x?: AppData;
   readonly meta: DirectoryMeta;
 };
 type ScimCompareOp = "eq" | "ne" | "co" | "sw";
@@ -68,17 +77,19 @@ type ScimPatchOp = {
   readonly value?: unknown;
 };
 type DirectoryStore = {
-  getUser(tenant: string, id: string): Promise<DirectoryUser | null>;
-  findUsers(tenant: string, filter: ScimFilter | undefined, page: ScimPage): Promise<ScimPageResult<DirectoryUser>>;
-  putUser(tenant: string, user: DirectoryUser): Promise<DirectoryUser>;
-  patchUser(tenant: string, id: string, ops: readonly ScimPatchOp[]): Promise<DirectoryUser>;
-  deleteUser(tenant: string, id: string): Promise<void>;
-  getGroup(tenant: string, id: string): Promise<DirectoryGroup | null>;
-  findGroups(tenant: string, filter: ScimFilter | undefined, page: ScimPage): Promise<ScimPageResult<DirectoryGroup>>;
-  putGroup(tenant: string, group: DirectoryGroup): Promise<DirectoryGroup>;
-  patchGroup(tenant: string, id: string, ops: readonly ScimPatchOp[]): Promise<DirectoryGroup>;
-  deleteGroup(tenant: string, id: string): Promise<void>;
-  groupsFor(tenant: string, userId: string): Promise<readonly DirectoryGroup[]>;
+  /** Shown in errors and events; optional, as on every extension interface. */
+  readonly name?: string;
+  getUser(tenant: string, id: string): DirectoryUser | null | Promise<DirectoryUser | null>;
+  findUsers(tenant: string, filter: ScimFilter | undefined, page: ScimPage): ScimPageResult<DirectoryUser> | Promise<ScimPageResult<DirectoryUser>>;
+  putUser(tenant: string, user: DirectoryUser): DirectoryUser | Promise<DirectoryUser>;
+  patchUser(tenant: string, id: string, ops: readonly ScimPatchOp[]): DirectoryUser | Promise<DirectoryUser>;
+  deleteUser(tenant: string, id: string): void | Promise<void>;
+  getGroup(tenant: string, id: string): DirectoryGroup | null | Promise<DirectoryGroup | null>;
+  findGroups(tenant: string, filter: ScimFilter | undefined, page: ScimPage): ScimPageResult<DirectoryGroup> | Promise<ScimPageResult<DirectoryGroup>>;
+  putGroup(tenant: string, group: DirectoryGroup): DirectoryGroup | Promise<DirectoryGroup>;
+  patchGroup(tenant: string, id: string, ops: readonly ScimPatchOp[]): DirectoryGroup | Promise<DirectoryGroup>;
+  deleteGroup(tenant: string, id: string): void | Promise<void>;
+  groupsFor(tenant: string, userId: string): readonly DirectoryGroup[] | Promise<readonly DirectoryGroup[]>;
 };
 type ScimTokenOptions = {
   readonly hash: "sha256";
@@ -91,11 +102,13 @@ type DirectoryChange = {
   readonly kind: "session-revoked" | "changed";
 };
 type ScimHandlerOptions = {
-  readonly store: DirectoryStore;
+  readonly directory: DirectoryStore;
   readonly tenant: string | ((request: Request) => string | Promise<string>);
   readonly token?: ScimTokenOptions;
   readonly verifier?: TokenVerifier;
   readonly audience?: string;
+  /** With `verifier`: where the JWT names its tenant (`claims.tenant`); default `tenant`, then `tid`. */
+  readonly claims?: Pick<ClaimsMap, "tenant">;
   readonly groupRoles?: Readonly<Record<string, readonly string[]>>;
   readonly assignable?: readonly string[];
   readonly sink?: DecisionSink;
@@ -125,6 +138,10 @@ declare class DirectoryNotFoundError extends Error {
   readonly code: "not-found";
   constructor(message?: string);
 }
+/** Matches by `name` and `code`, so an error from another copy of the module still maps. */
+declare function isDirectoryUniquenessError(error: unknown): error is DirectoryUniquenessError;
+/** Matches by `name` and `code`, so an error from another copy of the module still maps. */
+declare function isDirectoryNotFoundError(error: unknown): error is DirectoryNotFoundError;
 //#endregion
 //#region src/scim/auth.d.ts
 type ScimCredential = {
@@ -146,6 +163,7 @@ declare function authenticateScim(input: {
   readonly audience?: string;
   readonly token?: ScimTokenOptions;
   readonly verifier?: TokenVerifier;
+  readonly claims?: Pick<ClaimsMap, "tenant">;
 }): Promise<ScimAuthResult>;
 declare function sha256Hex(value: string): string;
 //#endregion
@@ -174,4 +192,4 @@ declare function directoryMembershipSource(store: DirectoryStore, options?: Dire
 //#region src/scim/store.d.ts
 declare function memoryDirectoryStore(): DirectoryStore;
 //#endregion
-export { ScimPageResult as A, LIST_SCHEMA as C, ScimFilter as D, SCIM_CONTENT_TYPE as E, ScimTokenOptions as M, USER_SCHEMA as N, ScimHandlerOptions as O, GROUP_SCHEMA as S, ROLES_EXTENSION as T, DirectoryNotFoundError as _, scimHandler as a, DirectoryUser as b, parseScimFilter as c, serviceProviderConfig as d, authenticateScim as f, DirectoryMembershipSourceOptions as g, DirectoryGroup as h, tenantFromPath as i, ScimPatchOp as j, ScimPage as k, resourceTypes as l, DirectoryChange as m, directoryMembershipSource as n, filterSupported as o, sha256Hex as p, normalizePatchOps as r, matchFilter as s, memoryDirectoryStore as t, schemas as u, DirectoryStore as v, PATCH_SCHEMA as w, ERROR_SCHEMA as x, DirectoryUniquenessError as y };
+export { ScimPage as A, GROUP_SCHEMA as C, SCIM_CONTENT_TYPE as D, ROLES_EXTENSION as E, isDirectoryNotFoundError as F, isDirectoryUniquenessError as I, ScimPatchOp as M, ScimTokenOptions as N, ScimFilter as O, USER_SCHEMA as P, ERROR_SCHEMA as S, PATCH_SCHEMA as T, DirectoryMembershipSourceOptions as _, scimHandler as a, DirectoryUniquenessError as b, parseScimFilter as c, serviceProviderConfig as d, authenticateScim as f, DirectoryGroup as g, DirectoryChange as h, tenantFromPath as i, ScimPageResult as j, ScimHandlerOptions as k, resourceTypes as l, APP_DATA_EXTENSION as m, directoryMembershipSource as n, filterSupported as o, sha256Hex as p, normalizePatchOps as r, matchFilter as s, memoryDirectoryStore as t, schemas as u, DirectoryNotFoundError as v, LIST_SCHEMA as w, DirectoryUser as x, DirectoryStore as y };

package/dist/index-Cp_ilKi1.d.ts

@@ -0,0 +1,91 @@
+import { T as Policy, rr as Principal, ut as TokenSigner } from "./policy-types-n0uRTsW8.js";
+import { E as SsfPermDockOptions, T as SsfPermDock, _ as SetSubject, c as PushSetOptions, d as SetDelivery, g as SetQueue, h as SetPollHandlerOptions, m as SetEvent, t as CaepCommon, v as SignSetOptions } from "./types-C791HFu9.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/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/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 { setPollHandler as _, CaepTokenClaimsChange as a, RiscEvents as c, caepEvents as d, pushSet as f, memorySetQueue as g, streamVerificationEvent as h, CaepEvents as i, 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, createPermDock as v };

package/dist/index-CueFnxQc.d.ts

@@ -0,0 +1,110 @@
+import { T as Policy, Zt as DeliveryChannel, j as PolicyVocabulary, q as DecisionSink, rr as Principal } from "./policy-types-n0uRTsW8.js";
+import { w as Permission } from "./vocabulary-CN8H_9UF.js";
+import { t as Operation } from "./operations-X0VM7F3m.js";
+import { p as PrincipalSource, r as PermDock } from "./permdock-SV8ZINYT.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-BtHtcKMr.js";
+import { l as WebhookSigner } from "./standard-webhooks-rbD7LS6h.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/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 { DeliveryPermDock as a, MemoryDelivery as c, memoryDeliveryTransport as d, Audience as f, subscribersFor as g, audience as h, isDeliveryTarget as i, MemoryDeliveryTransport as l, SubscriberEvent as m, webhookTransport as n, DeliveryPermDockOptions as o, AudienceOptions as p, isAddrSpec as r, createPermDock as s, WebhookTransportOptions as t, MemoryDeliveryTransportOptions as u };