@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/managers/OidcManager.d.ts

@@ -0,0 +1,210 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import BaseManager, { type BackupData } from './BaseManager.js';
+import type { AuditEvent as OidcAuditEvent, SignInContext } from '@jwilleke/oidc-auth-server';
+import type { PermissionSubject } from './UserManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+export declare const OIDC_PREFIX = "oidc-auth-server.";
+export declare const OIDC_ENABLED_KEY = "oidc-auth-server.enabled";
+/** Where the provider is mounted, below the base-url. */
+export declare const OIDC_MOUNT = "/oidc";
+/** ngdpbase's own sign-in and consent route for a pending interaction (#1572). */
+export declare const OIDC_INTERACTION_PREFIX = "/interaction/";
+/** The package reads these from the environment only; they are generated here when unset. */
+export declare const OIDC_JWKS_ENV = "OIDC_AUTH_SERVER_JWKS";
+export declare const OIDC_COOKIE_KEYS_ENV = "OIDC_AUTH_SERVER_COOKIE_KEYS";
+/** The `acr` values ngdpbase's sign-in record can carry (SessionSignIn.acr). */
+export declare const NGDPBASE_ACR_VALUES: string[];
+/**
+ * The claim that says the account is a test account (#1805): always a boolean,
+ * so a client can tell "real" (`false`) from "not asked" (absent). Released
+ * with the `profile` scope — the provider drops any claim no scope names.
+ */
+export declare const TEST_ACCOUNT_CLAIM = "test_account";
+/** The package's scope-to-claims map with `test_account` added to `profile`. */
+export declare function withTestAccountClaim(scopeClaims: Record<string, string[]> | undefined): Record<string, string[]>;
+type Handler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+type OidcPackage = typeof import('@jwilleke/oidc-auth-server');
+type AuthServer = ReturnType<OidcPackage['createAuthServer']>;
+/** ngdpbase's own API as a resource server: tokens for it name this audience (#1576). */
+export declare function apiResourceFor(baseUrl: string): string;
+/**
+ * The AAL a token's `acr` stands for (#1576). `acr` names the strongest
+ * phishing resistance when there is one, hiding the level behind it, so
+ * `phr` and `phrh` read conservatively as 2: `phrh` reaches AAL3 only with
+ * more than a token says, and no shipped role needs AAL3. Unknown reads as 1.
+ */
+export declare function aalOfAcr(acr: unknown): 1 | 2 | 3;
+/** The permissions an app may be delegated: every defined one a delegation may carry. */
+export declare function delegablePermissions(definitions: unknown): string[];
+/** What a verified access token for ngdpbase's API stands for. */
+export interface VerifiedAccessToken {
+    username: string;
+    clientId: string;
+    grantId: string;
+    scopes: string[];
+    aal: 1 | 2 | 3;
+}
+/** The issuer for a base-url: no trailing slash, the mount appended. */
+export declare function issuerFor(baseUrl: string): string;
+/** Plain HTTP is allowed only on this machine, where there is no wire to protect. */
+export declare function isLoopbackHttp(issuer: string): boolean;
+/** The operator's `oidc-auth-server.*` keys, minus ngdpbase's own; a derived key set by hand is a problem. */
+export declare function operatorOidcConfig(custom: Record<string, unknown>): {
+    config: Record<string, unknown>;
+    problems: string[];
+};
+/** One app or device a person approved, as their profile lists it (#1601). */
+export interface ApprovedApp {
+    grantId: string;
+    clientId: string;
+    name: string;
+    /** Approved through the device flow (RFC 8628): the client may use the device grant. */
+    device: boolean;
+    /** Everything the grant allows: OIDC scopes and API scopes, de-duplicated. */
+    scopes: string[];
+    /** ISO 8601. */
+    approvedAt: string | null;
+    expiresAt: string | null;
+    /**
+     * The app holds a refresh key, so its access is renewed automatically with
+     * a new key each time (#1764). False: it has only what it was given, which
+     * ends with the grant.
+     */
+    refreshable: boolean;
+    /** ISO 8601: when its key was last renewed; null when it has not been yet (#1764). */
+    renewedAt: string | null;
+    /** #1762 slice 6: who approved it while acting for this person; null when they approved it themselves. */
+    approvedBy: string | null;
+    /** The proxy grant it was approved under; null when the person approved it. */
+    proxyGrantId: string | null;
+}
+/** One RSA signing key as a JWKS, the shape OIDC_AUTH_SERVER_JWKS holds. */
+export declare function generateJwks(): string;
+export declare class OidcManager extends BaseManager {
+    private store;
+    private options;
+    private pkg;
+    private auth;
+    private issuer;
+    private apiResource;
+    /** The permissions an app may ask for on ngdpbase's API (`delegablePermissions`). */
+    private apiScopes;
+    constructor(engine: WikiEngine);
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Build the server with the `trust proxy` decision app.ts made for Express.
+     * Returns null when the manager is off or refused; the caller mounts nothing.
+     */
+    start(settings: {
+        trustProxy: boolean;
+    }): Handler | null;
+    /** The package's interaction helpers for the sign-in bridge (#1572); null when not serving. */
+    interactions(): AuthServer['interactions'] | null;
+    /**
+     * The pending request's own parameters (`prompt`, `max_age`, …), which the
+     * package's `details()` does not carry, and when it began (epoch seconds).
+     * The bridge reads them to refuse a request for a fresh sign-in it cannot
+     * give yet (#1525), and to accept one made after the request began.
+     */
+    pendingRequest(req: IncomingMessage, res: ServerResponse): Promise<{
+        params: Record<string, unknown>;
+        startedAt: number;
+    }>;
+    /** The audience a token for ngdpbase's API names; empty when off. */
+    getApiResource(): string;
+    /**
+     * Verify an access token presented to ngdpbase's API (#1576), in process:
+     * it must exist, be unexpired, name this API as its audience, not be bound
+     * to a key we do not check, and belong to an account that still passes
+     * findAccount (active; no password change since the sign-in, #1592).
+     * Null otherwise — never a reason, since the caller is unauthenticated.
+     */
+    verifyAccessToken(token: string): Promise<VerifiedAccessToken | null>;
+    /**
+     * Why `subject` may not approve an app asking for `scope`, in plain words,
+     * or null when they may (#1762 slice 6). Only someone acting for the person
+     * under a proxy grant is asked: each permission the app asks for on
+     * ngdpbase's API must be one the decision point permits that subject, which
+     * under a proxy is the grant, the represented person and the person acting
+     * all at once. The person themselves is not asked, as before: what an app
+     * of theirs can do is bounded by what they hold, at every use.
+     */
+    proxyApprovalRefusal(subject: PermissionSubject, scope: string): Promise<string | null>;
+    /**
+     * Finish the consent step (#1572) for `subject`. Acting for someone (#1762
+     * slice 6), the approval is also recorded beside the grant: who approved it
+     * and under which proxy grant, so the profile can say so, ending the proxy
+     * grant revokes it, and it works only while that grant is in force. Recorded
+     * in the audit log as an approval naming both people.
+     */
+    finishConsent(req: IncomingMessage, res: ServerResponse, subject: PermissionSubject): Promise<void>;
+    /** The proxy approvals of live grants, by grant id (#1762 slice 6). */
+    private proxyApprovals;
+    /**
+     * An app approved under a proxy grant works only while that grant is in
+     * force (#1762 slice 6), asked of AuthManager, which owns the grants; no
+     * answer is a refusal. One the person approved is not affected.
+     */
+    private approvalInForce;
+    /**
+     * The apps and devices `username` approved (#1601): one per live grant,
+     * newest first. Empty when the provider is off.
+     */
+    listGrants(username: string): Promise<ApprovedApp[]>;
+    /**
+     * End one of `username`'s grants and every code and token under it (#1601).
+     * False when no such grant is theirs — never revokes another person's.
+     * Recorded as oidcgrant-revoke by whoever revoked it (`by`, the owner when
+     * not given), naming the owner, as an agent token's revoke is (#1764);
+     * under a proxy grant, naming the person acting too (#1762 slice 6).
+     */
+    revokeGrant(username: string, grantId: string, by: PermissionSubject): Promise<boolean>;
+    /** What to call a client on the consent page: its registered name, else its id. */
+    clientName(clientId: string): Promise<string>;
+    /**
+     * End every provider session of an account (#1572), so signing out of
+     * ngdpbase also signs out of /oidc: the provider's own session cookie would
+     * otherwise keep finishing sign-ins for someone who left. Grants stay —
+     * consent is remembered — and tokens already issued run to their expiry.
+     */
+    endSessionsFor(username: string): Promise<number>;
+    /** The issuer once configured; empty when off. */
+    getIssuer(): string;
+    /**
+     * The person's claims for the package, or undefined — which fails the
+     * request closed — when the account is gone or disabled, or when this
+     * sign-in is older than the account's last password change (#1592): an app
+     * keeps nothing past a password change, as no web session does (#1482).
+     * Never roles: a session can hold fewer roles than the account (#1569).
+     * `test_account` is always a boolean (#1805), released with `profile`.
+     */
+    findAccount(accountId: string, signIn?: SignInContext): Promise<Record<string, unknown> | undefined>;
+    /**
+     * Record one provider event in ngdpbase's audit log (#1575). The package
+     * never passes a token, code or secret; the person is the account, the
+     * resource is the app. Returns the promise so the package can count a
+     * report the sink failed to take.
+     */
+    recordEvent(event: OidcAuditEvent): Promise<void>;
+    /**
+     * One provider event into the audit log. `revoker` is ngdpbase's own
+     * revoke (#1764): the record is by the person who revoked, naming the
+     * owner; under a proxy grant `user` is the represented person and `actor`
+     * the person acting (#1762 slice 6). Null for the provider's own events.
+     */
+    private writeEvent;
+    shutdown(): Promise<void>;
+    /**
+     * Who had granted which client access, for incident response — not a
+     * restorable copy. The store's rows are short-lived or hold presentable
+     * session ids; a restored one would revive access somebody may have ended.
+     */
+    backup(): Promise<BackupData>;
+    /** Refuse: there is nothing to restore from; people sign in again and clients re-consent. */
+    restore(_backupData: BackupData): Promise<void>;
+    /** Generate the signing keys and cookie keys into the instance .env when nothing supplies them. */
+    private ensureKeys;
+    /** Enabled but unusable: say why, loudly, and mount nothing. */
+    private refuse;
+}
+export default OidcManager;

package/lib/src/managers/OrganizationManager.d.ts

@@ -0,0 +1,107 @@
+import BaseManager, { type ManagerStats } from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { Organization, OrganizationUpdate } from '../types/Organization.js';
+import type { OrganizationProvider } from '../types/OrganizationProvider.js';
+/**
+ * Subset of install-form data this manager needs to seed the anchor org.
+ * Kept narrow so InstallService and tests can pass plain objects without
+ * importing the full InstallData type.
+ */
+export interface OrganizationSeedData {
+    orgName: string;
+    orgLegalName?: string;
+    orgDescription?: string;
+    orgFoundingDate?: string;
+    orgUrl?: string;
+    orgAddressLocality?: string;
+    orgAddressRegion?: string;
+    orgAddressCountry?: string;
+    /** Email used for the install's primary technical contact. */
+    adminEmail?: string;
+    /** Filename to write under storagedir, e.g. "acme-corporation.json". */
+    filename?: string;
+}
+/**
+ * OrganizationManager — canonical core record for organizations (#617).
+ *
+ * Owns the on-disk Organization records end-to-end. The install's anchor
+ * org is identified by `ngdpbase.application.organization.file`; the rest
+ * of the org files in `storagedir` are additional orgs in a multi-org
+ * install. UserManager resolves `Person.memberOf` via `getInstallOrg()`,
+ * so the anchor org is the implicit parent for every user-paired Person.
+ */
+declare class OrganizationManager extends BaseManager {
+    readonly description = "Canonical Organization records (#617)";
+    private provider;
+    private providerClass?;
+    private installOrgCache;
+    private byIdCache;
+    private byFileCache;
+    private metricsRef;
+    constructor(engine: WikiEngine);
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /** Provider accessor, mainly for tests. */
+    getProvider(): OrganizationProvider | null;
+    /**
+     * Create the anchor organization from the instance's own identity (#1027).
+     *
+     * Written to the organizations storage directory like any other record, so it
+     * is editable through the admin UI afterwards. That is the point: an org
+     * supplied by the deployment (a mounted ConfigMap file, say) is read-only and
+     * cannot be corrected without a redeploy. Application configuration should
+     * not require editing deployment manifests.
+     *
+     * Filename follows the convention the install wizard uses — the base-url host
+     * with dots as hyphens — so an instance seeded here and one installed through
+     * the wizard are indistinguishable afterwards.
+     */
+    private seedAnchorOrganization;
+    /**
+     * Return the install's anchor org, resolving or seeding one if needed (#1027).
+     *
+     * Three tiers, in order:
+     *
+     *   1. `ngdpbase.application.organization.file` names it — what the install
+     *      wizard writes.
+     *   2. No key, but exactly one org record exists — adopt it. An install with
+     *      a single organization has no ambiguity about which one anchors it, and
+     *      requiring a config key to state the obvious is what left headless
+     *      deployments silently unable to assign any role.
+     *   3. Nothing at all — seed a minimal record from the instance's own
+     *      identity. An instance always belongs to *something*; having no anchor
+     *      is never the correct end state, it just breaks role assignment.
+     *
+     * Deliberately never writes the config key back. Instance config is a
+     * read-only mount on containerised deployments, so a resolution strategy that
+     * depends on persisting a key would work locally and fail exactly where this
+     * problem actually bites.
+     */
+    getInstallOrg(): Promise<Organization | null>;
+    getById(id: string): Promise<Organization | null>;
+    getByFile(filename: string): Promise<Organization | null>;
+    /** #1006: how many organizations this instance holds. Count only. */
+    getManagerStats(): Promise<ManagerStats>;
+    list(): Promise<Organization[]>;
+    create(org: Organization, filename?: string): Promise<Organization>;
+    update(id: string, patch: OrganizationUpdate): Promise<Organization | null>;
+    delete(id: string): Promise<boolean>;
+    /**
+     * Clear all caches. Called on every write — the simplest correct
+     * invalidation. Per-key invalidation can come later if needed.
+     * Public so callers (e.g., admin "rebuild" tools) can force a cache miss.
+     */
+    invalidateCache(): void;
+    /**
+     * Seed the install's anchor org from install-form data. Idempotent: if an
+     * org file with the configured filename already exists, this is a no-op
+     * (returns the existing record). The org JSON-LD file at
+     * `<storagedir>/<file>` is the single source of truth for `name`, `url`,
+     * `address`, etc. — those fields live IN THE FILE, not in config. Config
+     * holds only the pointer (`ngdpbase.application.organization.file`).
+     */
+    seedFromConfig(data: OrganizationSeedData): Promise<Organization | null>;
+    private requireProvider;
+    private getMetrics;
+    private normalizeProviderName;
+}
+export default OrganizationManager;