@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/types/Page.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Page type definitions for ngdpbase
+ *
+ * This module defines the core types for wiki pages, including frontmatter
+ * metadata, page content, and page information structures used throughout
+ * the application.
+ */
+/**
+ * Page frontmatter metadata
+ *
+ * Metadata stored in YAML frontmatter at the top of each markdown file.
+ * All pages must have at minimum: title, uuid, and lastModified.
+ */
+export interface PageFrontmatter {
+    /** Page title (required) */
+    title: string;
+    /** Unique identifier (UUID v4) */
+    uuid: string;
+    /** Last modification timestamp (ISO 8601 format) */
+    lastModified: string;
+    /**
+     * Page creation timestamp (ISO 8601 format).
+     *
+     * Set ONCE on first save and preserved by every subsequent save —
+     * `FileSystemProvider.savePage()` carries it forward from the on-disk
+     * frontmatter so updates never overwrite it. Optional in the type
+     * because pre-#754 pages were written without it; the migration
+     * script `scripts/migrate-page-created.ts` backfills existing pages
+     * from v1-manifest `dateCreated` → file mtime → `lastModified`.
+     */
+    created?: string;
+    /** System-defined category (optional) */
+    'system-category'?: string;
+    /** User-defined category (optional) */
+    category?: string;
+    /** User-defined keywords/tags */
+    'user-keywords'?: string[];
+    /** Machine/automation keywords (#869 bucket model): AI classification and
+     *  provenance marks (e.g. 'capture'). Operator-curated vocabulary. */
+    'system-keywords'?: string[];
+    /** URL slug for pretty URLs */
+    slug?: string;
+    /** Page author (user ID or 'system') */
+    author?: string;
+    /** Last editor (user ID or 'system') */
+    editor?: string;
+    /** Whether a system/documentation page has been user-modified */
+    'user-modified'?: boolean;
+    /** Page template to use for rendering */
+    template?: string;
+    /** Whether page is published/visible */
+    published?: boolean;
+    /**
+     * Editorial lifecycle state (#893, Slice 1 of #869): 'draft' | 'review' |
+     * 'published'. Absent means 'published'. Replaces the lifecycle terms that
+     * previously lived in user-keywords / system-keywords; the page door
+     * migrates them here on save.
+     */
+    status?: string;
+    /** Parent page UUID for hierarchical structure */
+    parent?: string;
+    /** Sort order for navigation */
+    order?: number;
+    /** Name of the add-on that originally seeded this page, if any */
+    addon?: string;
+    /**
+     * #946 — name of the agent token that CREATED this page, if any.
+     * Immutable: a durable fact about the page's origin, never overwritten by a
+     * later edit. Server-owned; stripped from caller-supplied frontmatter.
+     */
+    'created-via-token'?: string;
+    /**
+     * #946 — name of the agent token used for the MOST RECENT revision.
+     * Cleared when a human writes, so it always answers "is this currently
+     * agent-maintained?" rather than "was it ever". Pairs with `editor`, as
+     * `created-via-token` pairs with `author`. Server-owned.
+     */
+    'via-token'?: string;
+    /** Roles or usernames allowed to view this page (front matter access control) */
+    audience?: string[];
+    /**
+     * The boolean setting this page belongs to (#1677). While that setting is
+     * not `true` the page reads as not found and is left out of listings — a
+     * help page for a feature that is off. See `src/utils/pageFeature.ts`.
+     */
+    'requires-setting'?: string;
+    /**
+     * Whether the page is private — accessible only to the page creator and admins.
+     *
+     * Peer of `audience` and `author-lock`; canonical signal for PolicyInformationPoint's tier-0
+     * private check. When true, all other per-page rules (audience, access, author-lock)
+     * are bypassed and the page is stored in a separate per-creator location.
+     *
+     * #639: top-level field added in Slice C; user-keywords back-compat scan dropped
+     * in Slice E (v3.7.0). All datasets migrated; this field is the only source of truth.
+     */
+    private?: boolean;
+    /** Per-action principal lists — overrides audience for the named action */
+    access?: {
+        view?: string[];
+        edit?: string[];
+        delete?: string[];
+        [key: string]: string[] | undefined;
+    };
+    /** Additional custom metadata */
+    [key: string]: unknown;
+}
+/**
+ * Complete wiki page object
+ *
+ * Represents a full page with content and metadata. This is the primary
+ * data structure returned by PageProvider.getPage().
+ */
+export interface WikiPage {
+    /** Page title */
+    title: string;
+    /** Unique identifier (UUID v4) */
+    uuid: string;
+    /** Markdown content (without frontmatter) */
+    content: string;
+    /** Frontmatter metadata */
+    metadata: PageFrontmatter;
+    /** Absolute file path to the page file */
+    filePath: string;
+    /** Location type (pages or required-pages) */
+    location?: 'pages' | 'required-pages';
+}
+/**
+ * Minimal page information for listings
+ *
+ * Used in page indexes, search results, and navigation where full content
+ * is not needed. This is stored in page-index.json.
+ */
+export interface PageInfo {
+    /** Page title */
+    title: string;
+    /** Unique identifier (UUID v4) */
+    uuid: string;
+    /** Absolute file path to the page file */
+    filePath: string;
+    /** Frontmatter metadata */
+    metadata: PageFrontmatter;
+    /** Location type */
+    location?: 'pages' | 'required-pages';
+    /** Last modification timestamp (from metadata) */
+    lastModified?: string;
+    /** Creation timestamp (from metadata, #754) */
+    created?: string;
+    /** Page author (from metadata) */
+    author?: string;
+    /** Last editor (from metadata) */
+    editor?: string;
+    /** Category (from metadata) */
+    category?: string;
+    /** URL slug (from metadata) */
+    slug?: string;
+}
+/**
+ * Page save options
+ *
+ * Options passed when saving a page to control versioning, author tracking,
+ * and other save behaviors.
+ */
+export interface PageSaveOptions {
+    /** User ID performing the save */
+    author?: string;
+    /** Change type (create, update, minor, major) */
+    changeType?: 'create' | 'update' | 'minor' | 'major';
+    /** Commit message/change description */
+    message?: string;
+    /** Whether to create a version entry */
+    createVersion?: boolean;
+    /** Additional metadata to merge */
+    additionalMetadata?: Partial<PageFrontmatter>;
+    /** Preserve lastModified from metadata instead of setting to now (for import/migration use) */
+    preserveLastModified?: boolean;
+    /**
+     * The private name the page is at now, when this save moves it into
+     * another of its owner's vaults (#1505). The page, its history and its
+     * index entry go with it. Only a save that says so changes a page's vault;
+     * one that names another vault without it is refused.
+     */
+    moveFrom?: string;
+}
+/**
+ * Page search result
+ *
+ * Extended page info with search relevance scoring and highlighting.
+ */
+export interface PageSearchResult extends PageInfo {
+    /** Search relevance score (0-1) */
+    score: number;
+    /** Highlighted snippets from content */
+    highlights?: string[];
+    /** Matched keywords */
+    matchedKeywords?: string[];
+}
+/**
+ * Page list options
+ *
+ * Options for filtering and sorting page lists.
+ */
+export interface PageListOptions {
+    /** Filter by category */
+    category?: string;
+    /** Filter by author */
+    author?: string;
+    /** Filter by keywords (AND logic) */
+    keywords?: string[];
+    /** Sort field */
+    sortBy?: 'title' | 'lastModified' | 'author' | 'category';
+    /** Sort order */
+    sortOrder?: 'asc' | 'desc';
+    /** Pagination: number of results per page */
+    limit?: number;
+    /** Pagination: page offset (0-based) */
+    offset?: number;
+    /** Include required-pages in results */
+    includeRequired?: boolean;
+}

package/lib/src/types/Person.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Schema.org Person type (#617)
+ *
+ * Canonical core record for a person. Stored as one JSON file per person
+ * under `ngdpbase.application.persons.storagedir`. Filename is `<uuid>.json`
+ * (where the uuid matches the v4 segment of `@id`).
+ *
+ * `@id` uses the urn:uuid:<v4> form because persons typically lack a
+ * canonical web URL. `identifier` matches `User.username` so existing auth
+ * records link cleanly to a Person.
+ *
+ * No embedded role-records — those live in the future person-contacts
+ * addon (#602) and are folded in at JSON-LD export time.
+ *
+ * @see https://schema.org/Person
+ */
+import type { PostalAddress, ContactPoint } from './Organization.js';
+/**
+ * Canonical Person record.
+ *
+ * Required: `@context`, `@type`, `@id`, `identifier`.
+ * Optional fields mirror schema.org Person.
+ */
+export interface Person {
+    '@context': 'https://schema.org';
+    '@type': 'Person';
+    /** urn:uuid:<v4> */
+    '@id': string;
+    /** Matches User.username so auth records link to this Person */
+    identifier: string;
+    /** Display name */
+    name?: string;
+    /** Given name (first name) */
+    givenName?: string;
+    /** Family name (last name) */
+    familyName?: string;
+    /** Email address */
+    email?: string;
+    /** Postal address */
+    address?: PostalAddress;
+    /** Contact points (work phone, mobile, etc.) */
+    contactPoint?: ContactPoint[];
+    /** ISO language tags this person knows */
+    knowsLanguage?: string[];
+    /** Profile/avatar image URL */
+    image?: string;
+    /** Other URLs that identify this person (LinkedIn, GitHub, etc.) */
+    sameAs?: string[];
+    /** Allow extension fields (additionalProperty, etc.) */
+    [key: string]: unknown;
+}
+/**
+ * Patch shape for update operations.
+ * `@context`/`@type` are immutable; `@id` and `identifier` cannot be changed via update.
+ */
+export type PersonUpdate = Partial<Omit<Person, '@context' | '@type' | '@id' | 'identifier'>>;

package/lib/src/types/PersonProvider.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Storage seam for Person records (#617)
+ *
+ * File system is the v1 default. Future providers (LDAP, external directory)
+ * implement the same interface and register without touching PersonManager.
+ */
+import type { BaseProvider } from './Provider.js';
+import type { Person, PersonUpdate } from './Person.js';
+export interface PersonProvider extends BaseProvider {
+    /** Return all persons the provider can see. */
+    list(): Promise<Person[]>;
+    /** Look up a person by `@id` (urn:uuid:<v4>). */
+    getById(id: string): Promise<Person | null>;
+    /**
+     * Look up a person by `identifier` — typically the matching User.username.
+     * Returns null if no Person carries that identifier.
+     */
+    getByIdentifier(identifier: string): Promise<Person | null>;
+    /** Persist a new Person. Returns the stored record. */
+    create(person: Person): Promise<Person>;
+    /** Apply a partial update by `@id`. Returns the updated record, or null if not found. */
+    update(id: string, patch: PersonUpdate): Promise<Person | null>;
+    /** Delete by `@id`. Returns true if a record was removed. */
+    delete(id: string): Promise<boolean>;
+}

package/lib/src/types/Policy.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Access policy shapes — declared once (#1431).
+ *
+ * A policy grants actions to subjects on resources. It is written in
+ * `ngdpbase.access.policies` and read through `ConfigurationManager`; nothing
+ * else grants.
+ *
+ * These were declared four times before this file: `PolicyManager` had its own
+ * `Policy`, `PolicyEvaluator` had `Policy`, `PolicySubject` and
+ * `PolicyResource`, `types/Share.ts` had `ShareResource` for the same
+ * `{ type, pattern }` pair, and `types/express.d.ts` re-declared that pair
+ * again because a `.d.ts` may not import a `.ts`. Four copies of one shape is
+ * how a field gets added to one and missed in the others.
+ */
+/** Who a policy grants to. `role` is the only type the evaluator matches today. */
+export interface PolicySubject {
+    /** `role`, and in future `user` or `group`. */
+    type: string;
+    value: string;
+}
+/**
+ * What a policy covers.
+ *
+ * `type` names the kind of thing — `page`, `media`, `asset`. `pattern` is
+ * matched against the resource's id; `*` is everything of that type.
+ */
+export interface PolicyResource {
+    type: string;
+    pattern: string;
+}
+/** One entry of `ngdpbase.access.policies`. */
+export interface Policy {
+    id: string;
+    name?: string;
+    description?: string;
+    /** Lower runs first, so a higher-priority deny lands last and wins. */
+    priority?: number;
+    /**
+     * `allow` or `deny`. Typed as a string because the value comes from
+     * configuration, where an operator can write anything; the evaluator treats
+     * everything that is not `deny` as an allow.
+     */
+    effect?: string;
+    subjects?: PolicySubject[];
+    resources?: PolicyResource[];
+    actions?: string[];
+    [key: string]: unknown;
+}
+/**
+ * The thing a decision is about.
+ *
+ * Deliberately NOT a page name. The policies have always modelled resources as
+ * `{ type, pattern }` — `ShareResource` says so in as many words: "Resource
+ * type the evaluator knows: page, media, …" — while the call that asked for a
+ * decision flattened it to a page name, which is why assets, media and
+ * attachments each grew their own path.
+ *
+ * Deliberately not the domain object either. A decision takes a REFERENCE, so
+ * the PDP answers without loading anything — including when the answer is a
+ * flat no. An `AssetRecord` or a page's frontmatter is an ATTRIBUTE source: a
+ * PIP supplies it, and only when a policy actually depends on it. Passing the
+ * record would make every caller load it first, teach the PDP about each
+ * domain type in turn, and need a signature per type.
+ */
+export interface DecisionResource {
+    /**
+     * The kind of thing. This is the __permission target__ — the left half of
+     * every permission name: `page`, `asset`, `user`, `admin`, `comment`,
+     * `profile`, `search`, `share`, `store`, `token`. One vocabulary, declared
+     * once, rather than a second taxonomy beside the registry.
+     *
+     * Two inconsistencies to settle as resources start being used (#1431):
+     * shipped policies name only `page`, even on grants like `token-mint` and
+     * `user-edit`, so the clause is decorative for nine targets; and shares use
+     * `media` (`types/Share.ts`) where the permissions use `asset`.
+     */
+    type: string;
+    /**
+     * Which one. A page's name or uuid; an asset's id.
+     *
+     * An asset is identified by `id` AND `providerId` (`types/Asset.ts`), so a
+     * reference to one must be provider-qualified or it is ambiguous.
+     */
+    id: string;
+}
+/** What is being asked of the PDP. No resource means a capability question. */
+export interface DecisionRequest {
+    action: string;
+    resource?: DecisionResource;
+    /**
+     * What the PIP knows about the resource beyond its reference, for the
+     * policy resource types that match on it (#1504): a page's
+     * `system-category`. The PDP passes it through; it never loads it.
+     */
+    attributes?: Record<string, unknown>;
+    /**
+     * Whether a share's `resources` cover the thing being asked about.
+     *
+     * Supplied by the PEP because the answer depends on attributes the PDP does
+     * not hold — a page share is matched against the page's keywords, for
+     * instance. The PDP owns the RULE (a share must cover the resource); the
+     * caller supplies the match, which is the PIP half.
+     */
+    resourceCoverage?: (shareResources: readonly PolicyResource[]) => boolean;
+}
+/**
+ * What the PDP answers.
+ *
+ * `reason` is for the log and the audit record. A PEP enforces `permit` and
+ * chooses 401 vs 403 from whether the caller is authenticated — it must not
+ * branch on the reason, or the reason becomes an interface. The one exception
+ * is {@link STEP_UP_REASON}, read only by `ApiContext.enforceDeny` (#1431): the one
+ * refusal that offers a way forward (a fresh sign-in).
+ */
+export interface Decision {
+    permit: boolean;
+    /**
+     * Whether any policy spoke to this question at all.
+     *
+     * XACML's NotApplicable. Both outcomes refuse when `permit` is false, but
+     * they are different facts: a policy that said no is `policy_deny`, while
+     * no policy speaking is `default_deny`, and the audit trail must tell an
+     * assessor which one happened. Kept three-state for that, even though the
+     * page door no longer has a tier below this one to fall through to — the
+     * page-ACL markup tier it once fed was removed in #1431 step 7a.
+     *
+     * `permit` is always false when this is false — nothing has said yes.
+     */
+    applicable: boolean;
+    reason: string;
+}
+/**
+ * The reason a deny carries when the subject holds the permission but its
+ * sign-in is not fresh enough to act (#1635). Declared once: the PDP writes it
+ * and `ApiContext.enforceDeny` reads it to ask for a fresh sign-in.
+ */
+export declare const STEP_UP_REASON = "step-up";
+/** True when `pattern` covers `id` for a resource of that type. `*` is everything. */
+export declare function resourceMatches(pattern: string, id: string): boolean;

package/lib/src/types/Policy.js

@@ -0,0 +1,17 @@
+'use strict';
+/**
+ * The reason a deny carries when the subject holds the permission but its
+ * sign-in is not fresh enough to act (#1635). Declared once: the PDP writes it
+ * and `ApiContext.enforceDeny` reads it to ask for a fresh sign-in.
+ */
+export const STEP_UP_REASON = 'step-up';
+/** True when `pattern` covers `id` for a resource of that type. `*` is everything. */
+export function resourceMatches(pattern, id) {
+    if (pattern === '*')
+        return true;
+    if (pattern === id)
+        return true;
+    if (pattern.endsWith('*'))
+        return id.startsWith(pattern.slice(0, -1));
+    return false;
+}