@qlzt/dsh-api-remote-access 0.0.0-stage → 0.2.1-rc.2

package/lib/types/client/state.js

@@ -0,0 +1,182 @@
+/**
+ * React-free Client access state: the latest `remoteAccess/follow` snapshot
+ * and identity-stable boolean sources per resource and action.
+ * @module @qlzt/dsh-api-remote-access/src/client/state
+ */
+const CLOSED = Object.freeze({ kind: 'closed' });
+const OWNER_SNAPSHOT = Object.freeze({ kind: 'owner' });
+const GLOBAL_KEY = '\u0000global';
+/**
+ * Validate the opening baseline an index injection row assigned to the page.
+ * @param value - the injected global; `undefined` when the page carries none.
+ * @returns the baseline, or `undefined` when none was injected.
+ * @throws TypeError when the injected value is not a baseline frame.
+ */
+export function parseInjectedBaseline(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value) || value['type'] !== 'baseline')
+        throw new TypeError('remote access: the injected access snapshot is not a baseline frame');
+    if (value['owner'] === true)
+        return { type: 'baseline', owner: true };
+    const grants = value['grants'];
+    if (value['owner'] !== false || !Array.isArray(grants) || !grants.every(isGrant)) {
+        throw new TypeError('remote access: the injected access snapshot carries malformed grants');
+    }
+    return { type: 'baseline', owner: false, grants };
+}
+function isGrant(value) {
+    if (!isRecord(value) || !isResource(value['resource']))
+        return false;
+    const actions = value['actions'];
+    return Array.isArray(actions) && actions.every(action => typeof action === 'string');
+}
+function isResource(value) {
+    if (!isRecord(value) || typeof value['kind'] !== 'string')
+        return false;
+    return value['kind'] === 'global' || typeof value['id'] === 'string';
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Snapshot owner for one Client generation. Sources are cached per
+ * `(kind, id, action)` so Hook bindings keep their identity; each source
+ * computes its boolean from the current snapshot.
+ */
+export class ClientAccessState {
+    snapshot = CLOSED;
+    /** @param initial - the page's injected opening baseline; without one every answer is false until a baseline arrives. */
+    constructor(initial) {
+        if (initial !== undefined)
+            this.replace(initial);
+    }
+    listeners = new Set();
+    sources = new Map();
+    /**
+     * Answer for one action on the global resource.
+     * @param action - endpoint action the caller may invoke.
+     * @returns identity-stable boolean source.
+     */
+    global(action) {
+        return this.cached(GLOBAL_KEY, '', action);
+    }
+    /**
+     * Answer for one action on one resource of a declared kind.
+     * @param kind - declared resource kind.
+     * @param id - resource identity.
+     * @param action - endpoint action the caller may invoke.
+     * @returns identity-stable boolean source.
+     */
+    resource(kind, id, action) {
+        return this.cached(kind, id, action);
+    }
+    /**
+     * Replace the snapshot from one generation's opening frame.
+     * @param frame - owner or non-owner baseline.
+     */
+    replace(frame) {
+        if (frame.owner) {
+            this.publish(OWNER_SNAPSHOT);
+            return;
+        }
+        let global = new Set();
+        const resources = new Map();
+        // The baseline is unpublished, so its maps are filled in place.
+        for (const { resource, actions } of frame.grants) {
+            if (resource.kind === 'global') {
+                global = new Set(actions);
+                continue;
+            }
+            let grants = resources.get(resource.kind);
+            if (grants === undefined) {
+                grants = new Map();
+                resources.set(resource.kind, grants);
+            }
+            grants.set(resource.id, new Set(actions));
+        }
+        this.publish({ kind: 'granted', global, resources });
+    }
+    /**
+     * Apply one increment of the current generation.
+     * @param frame - `upsert` or `remove`.
+     */
+    update(frame) {
+        const current = this.snapshot;
+        if (current.kind !== 'granted')
+            return;
+        switch (frame.type) {
+            case 'upsert':
+                this.publish(withGrant(current, frame.grant));
+                return;
+            case 'remove':
+                this.publish(withGrant(current, { resource: frame.resource, actions: [] }, true));
+                return;
+            /* v8 ignore next -- the generated Remote codec validates this closed union. */
+            default:
+                return assertNever(frame);
+        }
+    }
+    /** Whether the current snapshot is the owner's, whose answers never depend on the stream. */
+    get owner() {
+        return this.snapshot.kind === 'owner';
+    }
+    /** The stream failed terminally: the owner keeps every answer; a non-owner's answers become false. */
+    unavailable() {
+        if (this.snapshot.kind !== 'owner')
+            this.publish(CLOSED);
+    }
+    cached(kind, id, action) {
+        const key = `${kind}\u0000${id}\u0000${action}`;
+        let source = this.sources.get(key);
+        if (source === undefined) {
+            source = {
+                getSnapshot: () => answer(this.snapshot, kind, id, action),
+                subscribe: (listener) => {
+                    this.listeners.add(listener);
+                    return () => { this.listeners.delete(listener); };
+                },
+            };
+            this.sources.set(key, source);
+        }
+        return source;
+    }
+    publish(next) {
+        this.snapshot = next;
+        for (const listener of [...this.listeners])
+            listener();
+    }
+}
+function answer(snapshot, kind, id, action) {
+    switch (snapshot.kind) {
+        case 'closed':
+            return false;
+        case 'owner':
+            return true;
+        case 'granted': {
+            const allowed = kind === GLOBAL_KEY ? snapshot.global : snapshot.resources.get(kind)?.get(id);
+            return allowed?.has(action) ?? false;
+        }
+        /* v8 ignore next -- closed union. */
+        default:
+            return assertNever(snapshot);
+    }
+}
+function withGrant(snapshot, grant, remove = false) {
+    const resource = grant.resource;
+    if (resource.kind === 'global')
+        return { ...snapshot, global: new Set(grant.actions) };
+    const resources = new Map(snapshot.resources);
+    const grants = new Map(resources.get(resource.kind));
+    if (remove)
+        grants.delete(resource.id);
+    else
+        grants.set(resource.id, new Set(grant.actions));
+    resources.set(resource.kind, grants);
+    return { ...snapshot, resources };
+}
+/* v8 ignore next 3 -- closed-union backstop. */
+function assertNever(value) {
+    throw new Error(`unreachable access frame: ${JSON.stringify(value)}`);
+}
+//# sourceMappingURL=state.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Host method-level access control. The Gateway asks `decide()` before it
+ * dispatches a non-owner call or forwards an event to a non-owner Peer; list
+ * methods filter items through `allows()`; every Peer reads its own access
+ * snapshot, first from the index and then from `follow()`. Business packages
+ * register one policy per non-owner principal kind.
+ * @module @qlzt/dsh-api-remote-access
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService, type Principal, type PrincipalMap, type RemoteAccessResource } from '@qlzt/dsh-typert-protocol';
+import type { RemoteAccessDecision, RemoteAccessFrame, RemoteAccessPolicy, RemoteAccessRequest } from './types.ts';
+export type * from './types.ts';
+export { REMOTE_ACCESS_SNAPSHOT_KEY } from './snapshot.ts';
+/** The opening frame of a snapshot generation. */
+export type RemoteAccessBaseline = Extract<RemoteAccessFrame, {
+    type: 'baseline';
+}>;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Host method-level access control for non-owner Peers. */
+        remoteAccess: RemoteAccessService;
+    }
+}
+/**
+ * Registry of access policies, the Gateway's access decisions, list
+ * filtering, and the per-Peer access snapshot. Every composition that mounts
+ * the Gateway mounts this service too.
+ */
+export declare class RemoteAccessService extends TypertRemoteService {
+    private readonly policies;
+    /** Policies whose failure was logged since the last `invalidate()`; their later failures stay silent. */
+    private readonly reported;
+    private readonly followers;
+    /** Aborted when this instance unloads; every open snapshot generation ends with it. */
+    private readonly lifetime;
+    /** @param ctx - owning Host plugin Context. */
+    constructor(ctx: Context);
+    /**
+     * Register the policy of one non-owner principal kind in the caller's
+     * fiber; open snapshots are recomputed on registration and removal.
+     * @param kind - the principal kind the policy serves; never `owner`.
+     * @param policy - business-owned bindings and refusal reasons for principals of `kind`.
+     * @returns disposer removing this policy.
+     * @throws Error when `kind` already has a policy.
+     */
+    registerPolicy<K extends Exclude<keyof PrincipalMap, 'owner'>>(kind: K, policy: RemoteAccessPolicy<PrincipalMap[K]>): () => void;
+    /**
+     * Report that the bindings or condition answers for `principal` may have
+     * changed. Business packages call this on every grant, revocation, mode
+     * change, and expiry; open snapshots re-push, and the next failure of each
+     * policy is logged again.
+     * @param principal - affected principal; omitted for every principal.
+     */
+    invalidate(principal?: Principal): void;
+    /**
+     * Gateway-only: decide one request whose resources the Gateway resolved.
+     * The owner is allowed, and so is `remoteAccess/follow`: every Peer reads
+     * its own snapshot. Otherwise the action is allowed only when, on every
+     * listed resource, some binding of the principal's policy names that
+     * resource, has a role listing the action, and has no condition or a
+     * condition that allows. `bindings()` is called once per decision.
+     * @param request - the caller or recipient, the action, the resources it
+     *   touches, and a call's arguments.
+     * @returns `allow`; or `deny` with `no-allow` when the principal kind has
+     *   no policy, the first refusing condition's reason on the first resource
+     *   no binding allows, else `explain()`'s reason, else `no-allow`;
+     *   `policy-failed` when `bindings()`, a condition, or `explain()` throws,
+     *   logged once per policy until the next `invalidate()`. The Gateway
+     *   throws `remote-access/denied` for a denied call and drops a denied event.
+     */
+    decide(request: RemoteAccessRequest<Principal>): RemoteAccessDecision;
+    /**
+     * Filter items inside a Remote method. The invocation is read from the
+     * Context that accessed this service, so call it as
+     * `this.ctx.remoteAccess.allows(resource)` from the Remote method. Each
+     * check reads the policy's bindings again, so a long-running stream sees
+     * binding changes from the next check on.
+     * @param resource - resource of one result item.
+     * @returns true for the owner and outside a Remote call; otherwise whether
+     *   the invocation's endpoint action is allowed on `resource` without call
+     *   arguments, false when the policy is absent or fails.
+     */
+    allows(resource: RemoteAccessResource): boolean;
+    /**
+     * The baseline a page opens with before its snapshot stream connects. A
+     * business package rendering a non-owner page assigns this value to
+     * {@link REMOTE_ACCESS_SNAPSHOT_KEY} after every index injection row,
+     * replacing the owner baseline the webServer index carries.
+     * @param principal - the page's caller identity.
+     * @returns the owner baseline for the owner; otherwise the principal's current grants.
+     */
+    snapshotFor(principal: Principal): RemoteAccessBaseline;
+    /**
+     * Stream the calling Peer's access snapshot: one baseline, then `upsert`
+     * and `remove` frames after each `invalidate()` and each policy
+     * registration or removal that changes a grant. The owner receives only
+     * `{ owner: true }`. The generation ends when `signal` aborts or this
+     * service unloads, so a reloaded service starts every reader from a fresh
+     * baseline.
+     * @param signal - generation cancellation.
+     * @returns the access frames of one generation.
+     */
+    follow(signal: AbortSignal): AsyncIterable<RemoteAccessFrame>;
+    /** One `bindings()` call; `undefined` after a logged failure. */
+    private bindingsOf;
+    /** Find a binding on `resource` whose role lists `action` and whose condition, if any, allows. */
+    private evaluate;
+    /** The refusal reason `explain()` names, else `no-allow`; `policy-failed` when it throws. */
+    private explain;
+    /**
+     * One grant per bound resource, in first-binding order: the endpoint
+     * actions of the resource's bindings that `decide()` would allow there
+     * without call arguments. A resource with no such action gets no grant;
+     * event actions stay out of the snapshot.
+     */
+    private grantsFor;
+    /** Log a policy failure once per policy until the next `invalidate()`; snapshots and lists ask many times per change. */
+    private report;
+}
+export default RemoteAccessService;
+//# sourceMappingURL=index.d.ts.map