@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/context/JobContext.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Who asked for a background job, and from where (#631).
+ *
+ * A job runs after its request has returned, so nothing about the request
+ * survives unless it is carried deliberately. `BackgroundJobManager.enqueue()`
+ * took a job id and nothing else, so the identity of whoever pressed the button
+ * was discarded at the call site — `WikiRoutes` logged
+ * `Page reindex requested by: jim` on one line and threw the name away on the
+ * next. The audit log, which #1148/#1149/#1150/#1156/#1158/#1138 exist to make
+ * trustworthy, could not say who reindexed anything.
+ *
+ * __Identity and provenance travel; authority does not.__ This carries who
+ * asked, from what origin, and whether a delegated token was involved. It
+ * deliberately does NOT carry resolved roles. A reindex enqueued at 09:00 and
+ * running at 09:12 must not authorise against 09:00's roles — demote or delete
+ * the user in between and the job would keep rights they no longer hold. That
+ * is the same reasoning `app.ts` gives for agent tokens: *"roles are resolved
+ * live per request — a token never carries a snapshot."*
+ *
+ * So a job that needs to make a permission decision asks for the permission at
+ * the moment of the decision, from `username`, via {@link toPermissionSubject}.
+ * The question is always a permission (P2); roles are lists policy refers to,
+ * carried by nothing and gating nothing.
+ *
+ * __This is a deliberate reduction, which is the thing #1164 punished.__ The
+ * difference is that there it was accidental: `AttachmentManager` rebuilt a
+ * subject from three fields and silently dropped `viaToken` while believing it
+ * forwarded everything. Here the reduction happens in exactly one place, losing
+ * roles is the point, and __`viaToken` must survive it__ — otherwise a job
+ * enqueued by a token-bearing request escapes the agent-token ceiling simply by
+ * becoming asynchronous.
+ */
+import type { JobSubject, AgentTokenGrant, ProxyClaim } from '../managers/UserManager.js';
+import type { ShareGrant } from '../types/Share.js';
+/**
+ * Where the work came from.
+ *
+ * Every origin is a caller; none of them is "a person" as far as this type is
+ * concerned. `request` acts for an identity the session authenticated — which
+ * may itself be an agent token acting under a delegation. The rest are the
+ * server acting for itself, and they are named for that reason rather than
+ * defaulting to anonymous: `schedule` and `boot` run as the system principal
+ * (#631, env-owned identity, authority resolved through policy like any other
+ * caller), and `operator` is a command line.
+ */
+export type JobOrigin = 'request' | 'schedule' | 'boot' | 'operator';
+/** The identity a background job runs under. Flat, and serialisable by construction. */
+export interface JobContext {
+    /** Who asked. The system principal for the origins where the server acts for itself. */
+    username: string;
+    /** From what context the work was requested. */
+    origin: JobOrigin;
+    /**
+     * The agent token the requesting call arrived with, when it did.
+     *
+     * Carried so a job cannot outrun the ceiling that capped the request. Whether
+     * a token-triggered job may run at all is #1173's decision — this makes the
+     * question answerable rather than invisible.
+     */
+    viaToken?: AgentTokenGrant;
+    /** The share the requesting call presented, when it did (#1222). Carried for the same reason. */
+    viaShare?: ShareGrant;
+    /** The proxy grant the requesting call acted under, when it did (#1762). Carried for the same reason: a job never runs as the represented person unbounded. */
+    viaProxy?: ProxyClaim;
+    /** The address the requesting call came from (#1179), when there was one. Provenance for the record. */
+    ipAddress?: string;
+    /** ISO 8601. When the work was requested, not when it ran. */
+    requestedAt: string;
+    /** Why, for origins with no person to ask. Free text, for the audit record. */
+    reason?: string;
+}
+/** The shape a request-bound context exposes; both WikiContext and ApiContext satisfy it. */
+export interface RequestIdentity {
+    username?: string | null;
+    viaToken?: AgentTokenGrant;
+    viaShare?: ShareGrant;
+    viaProxy?: ProxyClaim;
+    ipAddress?: string;
+}
+/**
+ * The username a request-origin job carries when the request had no identity.
+ *
+ * Anonymous, and deliberately NOT the system principal. This used to default
+ * to `'System'`, which was harmless while `'System'` named nobody. Under #631
+ * the principal is a configured name that resolves to the `admin` role, so a
+ * route that enqueued work without a `userContext` would have run that work
+ * as the system principal — a bypass reached by forgetting an argument. A
+ * missing identity is a visitor; nothing more.
+ */
+export declare const ANONYMOUS_USERNAME = "Anonymous";
+/**
+ * Derive a job context from the request that triggered the work.
+ *
+ * Takes the identity a route already holds — `req.userContext`, an
+ * `ApiContext`, or a `WikiContext`'s `userContext` — rather than a username
+ * string, so `viaToken` comes along instead of being dropped.
+ */
+export declare function jobContextFromRequest(identity: RequestIdentity | null | undefined, now?: Date): JobContext;
+/**
+ * A request-origin context that also says why (#1179).
+ *
+ * For an act inside a request that has no subject of its own yet, or acts for
+ * someone other than the caller: self-registration (the new account is the
+ * identity, the reason says so), an identity provider provisioning an account
+ * (the system principal is the identity, the reason names the provider), a
+ * sign-in refreshing login statistics. The reason is mandatory for the same
+ * cause as in `jobContextFromSystem`: an act that cannot say why is the one an
+ * assessor asks about.
+ */
+export declare function jobContextFromRequestWithReason(identity: RequestIdentity | null | undefined, reason: string, now?: Date): JobContext;
+/**
+ * An operator acting from the command line (#1179) — `scripts/restart-audit-chain.ts`
+ * and its kind. There is a person, named on the command, and no request; the
+ * origin says so, and the reason is the command's own.
+ */
+export declare function jobContextFromOperator(username: string, reason: string, now?: Date): JobContext;
+/**
+ * A job with no person behind it — boot, a schedule, a retention pass.
+ *
+ * `systemPrincipal` is the name configured in `.env` as `NGDPBASE_SYSTEM_USER`
+ * (#631), read through `PolicyInformationPoint.systemPrincipalName()`. It is a mandatory
+ * positional argument rather than a constant here because this module is flat
+ * and engine-free by design, and a hardcoded `'System'` would be a second
+ * source of truth for a value the environment owns — one that silently names
+ * nobody the moment an operator picks a different name.
+ *
+ * `reason` is required rather than optional. An ownerless action that cannot
+ * say why it happened is the thing an assessor asks about, and a default would
+ * be filled in by nobody. This is the constructor #1173 needs in order to
+ * delete the `hasPermission` string overload: once it exists, every caller has
+ * a context to pass, including code that runs with no request at all.
+ */
+export declare function jobContextFromSystem(systemPrincipal: string, reason: string, now?: Date): JobContext;
+/** As {@link jobContextFromSystem}, for work started by a timer rather than at boot. */
+export declare function jobContextFromSchedule(systemPrincipal: string, reason: string, now?: Date): JobContext;
+/**
+ * The subject for a permission check made *by* this job.
+ *
+ * `roles` is deliberately absent for EVERY origin, and the PDP (`permits`)
+ * resolves them from the username at decision time — which is what makes the
+ * answer current rather than a replay of enqueue time. For a request-origin
+ * job that is the requester's current roles. For a boot or schedule job the
+ * username is the system principal named in `.env` (#631), and it resolves to
+ * the roles `ngdpbase.system.roles` declares for it — `admin` by default —
+ * through the same policy door as everyone else (P2). No roles ride along in
+ * the context, so there is nothing here for a caller to widen.
+ *
+ * `viaToken` IS carried, so a job triggered through a delegated token is still
+ * held to that token's scopes.
+ */
+export declare function toPermissionSubject(ctx: JobContext): JobSubject;
+/** One line for a log or an audit record: who, from where, and how. */
+export declare function describeJobContext(ctx: JobContext): string;

package/lib/src/context/JobContext.js

@@ -0,0 +1,144 @@
+/**
+ * Who asked for a background job, and from where (#631).
+ *
+ * A job runs after its request has returned, so nothing about the request
+ * survives unless it is carried deliberately. `BackgroundJobManager.enqueue()`
+ * took a job id and nothing else, so the identity of whoever pressed the button
+ * was discarded at the call site — `WikiRoutes` logged
+ * `Page reindex requested by: jim` on one line and threw the name away on the
+ * next. The audit log, which #1148/#1149/#1150/#1156/#1158/#1138 exist to make
+ * trustworthy, could not say who reindexed anything.
+ *
+ * __Identity and provenance travel; authority does not.__ This carries who
+ * asked, from what origin, and whether a delegated token was involved. It
+ * deliberately does NOT carry resolved roles. A reindex enqueued at 09:00 and
+ * running at 09:12 must not authorise against 09:00's roles — demote or delete
+ * the user in between and the job would keep rights they no longer hold. That
+ * is the same reasoning `app.ts` gives for agent tokens: *"roles are resolved
+ * live per request — a token never carries a snapshot."*
+ *
+ * So a job that needs to make a permission decision asks for the permission at
+ * the moment of the decision, from `username`, via {@link toPermissionSubject}.
+ * The question is always a permission (P2); roles are lists policy refers to,
+ * carried by nothing and gating nothing.
+ *
+ * __This is a deliberate reduction, which is the thing #1164 punished.__ The
+ * difference is that there it was accidental: `AttachmentManager` rebuilt a
+ * subject from three fields and silently dropped `viaToken` while believing it
+ * forwarded everything. Here the reduction happens in exactly one place, losing
+ * roles is the point, and __`viaToken` must survive it__ — otherwise a job
+ * enqueued by a token-bearing request escapes the agent-token ceiling simply by
+ * becoming asynchronous.
+ */
+/**
+ * The username a request-origin job carries when the request had no identity.
+ *
+ * Anonymous, and deliberately NOT the system principal. This used to default
+ * to `'System'`, which was harmless while `'System'` named nobody. Under #631
+ * the principal is a configured name that resolves to the `admin` role, so a
+ * route that enqueued work without a `userContext` would have run that work
+ * as the system principal — a bypass reached by forgetting an argument. A
+ * missing identity is a visitor; nothing more.
+ */
+export const ANONYMOUS_USERNAME = 'Anonymous';
+/**
+ * Derive a job context from the request that triggered the work.
+ *
+ * Takes the identity a route already holds — `req.userContext`, an
+ * `ApiContext`, or a `WikiContext`'s `userContext` — rather than a username
+ * string, so `viaToken` comes along instead of being dropped.
+ */
+export function jobContextFromRequest(identity, now = new Date()) {
+    return {
+        username: identity?.username ?? ANONYMOUS_USERNAME,
+        origin: 'request',
+        ...(identity?.viaToken ? { viaToken: identity.viaToken } : {}),
+        ...(identity?.viaShare ? { viaShare: identity.viaShare } : {}),
+        ...(identity?.viaProxy ? { viaProxy: identity.viaProxy } : {}),
+        ...(identity?.ipAddress ? { ipAddress: identity.ipAddress } : {}),
+        requestedAt: now.toISOString()
+    };
+}
+/**
+ * A request-origin context that also says why (#1179).
+ *
+ * For an act inside a request that has no subject of its own yet, or acts for
+ * someone other than the caller: self-registration (the new account is the
+ * identity, the reason says so), an identity provider provisioning an account
+ * (the system principal is the identity, the reason names the provider), a
+ * sign-in refreshing login statistics. The reason is mandatory for the same
+ * cause as in `jobContextFromSystem`: an act that cannot say why is the one an
+ * assessor asks about.
+ */
+export function jobContextFromRequestWithReason(identity, reason, now = new Date()) {
+    return { ...jobContextFromRequest(identity, now), reason };
+}
+/**
+ * An operator acting from the command line (#1179) — `scripts/restart-audit-chain.ts`
+ * and its kind. There is a person, named on the command, and no request; the
+ * origin says so, and the reason is the command's own.
+ */
+export function jobContextFromOperator(username, reason, now = new Date()) {
+    return { username, origin: 'operator', reason, requestedAt: now.toISOString() };
+}
+/**
+ * A job with no person behind it — boot, a schedule, a retention pass.
+ *
+ * `systemPrincipal` is the name configured in `.env` as `NGDPBASE_SYSTEM_USER`
+ * (#631), read through `PolicyInformationPoint.systemPrincipalName()`. It is a mandatory
+ * positional argument rather than a constant here because this module is flat
+ * and engine-free by design, and a hardcoded `'System'` would be a second
+ * source of truth for a value the environment owns — one that silently names
+ * nobody the moment an operator picks a different name.
+ *
+ * `reason` is required rather than optional. An ownerless action that cannot
+ * say why it happened is the thing an assessor asks about, and a default would
+ * be filled in by nobody. This is the constructor #1173 needs in order to
+ * delete the `hasPermission` string overload: once it exists, every caller has
+ * a context to pass, including code that runs with no request at all.
+ */
+export function jobContextFromSystem(systemPrincipal, reason, now = new Date()) {
+    return {
+        username: systemPrincipal,
+        origin: 'boot',
+        requestedAt: now.toISOString(),
+        reason
+    };
+}
+/** As {@link jobContextFromSystem}, for work started by a timer rather than at boot. */
+export function jobContextFromSchedule(systemPrincipal, reason, now = new Date()) {
+    return { ...jobContextFromSystem(systemPrincipal, reason, now), origin: 'schedule' };
+}
+/**
+ * The subject for a permission check made *by* this job.
+ *
+ * `roles` is deliberately absent for EVERY origin, and the PDP (`permits`)
+ * resolves them from the username at decision time — which is what makes the
+ * answer current rather than a replay of enqueue time. For a request-origin
+ * job that is the requester's current roles. For a boot or schedule job the
+ * username is the system principal named in `.env` (#631), and it resolves to
+ * the roles `ngdpbase.system.roles` declares for it — `admin` by default —
+ * through the same policy door as everyone else (P2). No roles ride along in
+ * the context, so there is nothing here for a caller to widen.
+ *
+ * `viaToken` IS carried, so a job triggered through a delegated token is still
+ * held to that token's scopes.
+ */
+export function toPermissionSubject(ctx) {
+    return {
+        username: ctx.username,
+        isAuthenticated: true,
+        // #1212: said on purpose. "Roles absent" used to be the signal, and the
+        // type could not tell that from a caller that forgot them.
+        resolveRolesNow: true,
+        ...(ctx.viaToken ? { viaToken: ctx.viaToken } : {}),
+        ...(ctx.viaShare ? { viaShare: ctx.viaShare } : {}),
+        ...(ctx.viaProxy ? { viaProxy: ctx.viaProxy } : {})
+    };
+}
+/** One line for a log or an audit record: who, from where, and how. */
+export function describeJobContext(ctx) {
+    const via = ctx.viaToken ? ` via token ${ctx.viaToken.id} ("${ctx.viaToken.name}")` : '';
+    const why = ctx.reason ? ` — ${ctx.reason}` : '';
+    return `${ctx.username} (${ctx.origin})${via}${why}`;
+}