@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

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

@@ -0,0 +1,172 @@
+/**
+ * Share links (#842) — capability tokens granting anonymous access to a
+ * defined scope of content.
+ *
+ * The scope is a typed object (decision 6 extraction seam): future scope
+ * kinds add a discriminant + evaluator without changing the token model.
+ * v1 ships exactly one kind: keyword.
+ */
+/** v1 scope: everything carrying a keyword (media EXIF/XMP + page user-keywords). */
+export interface KeywordShareScope {
+    kind: 'keyword';
+    keyword: string;
+}
+/**
+ * A vault's content, shared by its owner (#1388): chosen pages, or the whole
+ * vault. Pages are named by uuid, so renaming one does not break the link.
+ * Only the current pages are covered, never their history.
+ */
+export interface VaultShareScope {
+    kind: 'vault';
+    /** The vault's owner — the only one who may issue, extend or revoke it. */
+    owner: string;
+    /** The vault id: `pages/vaults/{owner}/{vault}/`. */
+    vault: string;
+    /** Page uuids, or null for the whole vault, including pages added while the link is live. */
+    pages: string[] | null;
+}
+/** Union of all scope kinds. */
+export type ShareScope = KeywordShareScope | VaultShareScope;
+/** Fixed expiry choices (decision 4). `null` = until cancelled. */
+export type ShareTtl = '24h' | '7d' | '30d' | null;
+/**
+ * One share record — persisted as one JSON file per share.
+ *
+ * `id` is the management handle (list/revoke); `token` is the anonymous
+ * capability and never appears in management URLs.
+ */
+/**
+ * What a share delegates, in the policy resource shape (#1221, epic #1225).
+ * A share is a delegation by the user who issues it: `actions` it may perform
+ * and `resources` it may perform them on, never more than the issuer held at
+ * the time. #1222 evaluates them; this is the record.
+ */
+export interface ShareResource {
+    /** Resource type the evaluator knows: `page`, `media`, … */
+    type: string;
+    /** Match pattern. `keyword:<name>` means "everything carrying this keyword". */
+    pattern: string;
+}
+/** What a share delegates when the issuer asks for nothing more: read-only. */
+export declare const DEFAULT_SHARE_ACTIONS: readonly string[];
+/** Reserved keyword excluding content from every share (decision 1). */
+export declare const OWNER_ONLY_KEYWORD = "owner-only";
+/**
+ * What a request that presented a share token carries (#1222, epic #1225).
+ *
+ * The share-side twin of `AgentTokenGrant`: it rides on `PermissionSubject`
+ * as `viaShare`, and the evaluator applies it as a ceiling — the action must
+ * be one of `actions`, the resource must be covered by `resources`, the share
+ * must not have passed `expiresAt`, and `issuer` must STILL hold the action
+ * when the decision is made. A delegation, not a copy of authority: revoke
+ * the issuer's role and every share they issued stops on the next request.
+ */
+export interface ShareGrant {
+    /** The share's management id — what audit records name. */
+    id: string;
+    /** Username of the delegator; resolved live at every decision. */
+    issuer: string;
+    /** Actions delegated, a subset of what the issuer held at issue. */
+    actions: string[];
+    /** What the delegation covers. */
+    resources: ShareResource[];
+    /** ISO 8601 expiry, or null = until revoked. */
+    expiresAt: string | null;
+}
+/**
+ * Does a share cover a resource of `type` carrying `keywords`?
+ *
+ * The single reader of the `keyword:<name>` grammar. The evaluator asks it
+ * about a page's user-keywords; the share routes ask it about a media item's
+ * EXIF/XMP keywords. A pattern this function does not understand covers
+ * nothing — an unknown grammar is a refusal, never a wildcard — and content
+ * carrying `owner-only` is never covered, whatever else it carries.
+ */
+export declare function shareCoversResource(resources: readonly ShareResource[], type: string, keywords: readonly string[]): boolean;
+/**
+ * Does a share name the vault `owner/vault` at all — whole, or any page in it?
+ * The container half of a vault share: who may step into the vault. Which
+ * pages it may then read is {@link shareCoversVaultPage}.
+ */
+export declare function shareNamesVault(resources: readonly ShareResource[], owner: string, vault: string): boolean;
+/**
+ * Does a share cover this page? The one rule both page doors ask (the decider
+ * and the list filter): a page in a vault by its uuid or its whole vault
+ * (#1388), any other page by its user-keywords.
+ */
+export declare function shareCoversPage(resources: readonly ShareResource[], pageName: string, metadata: {
+    uuid?: string;
+    'user-keywords'?: string[];
+}): boolean;
+/** The vault a vault link covers, read from its resources, or null for any other share (#1388). */
+export declare function vaultOfShare(resources: readonly ShareResource[]): {
+    owner: string;
+    vault: string;
+} | null;
+/** Does a share cover the page `uuid` in the vault `owner/vault`? */
+export declare function shareCoversVaultPage(resources: readonly ShareResource[], owner: string, vault: string, uuid: string | undefined): boolean;
+/** The resources a scope names, in the shape the evaluator matches. */
+export declare function resourcesForScope(scope: ShareScope): ShareResource[];
+export interface ShareRecord {
+    /** Management identifier (UUID v4). */
+    id: string;
+    /** Capability token — 64-char crypto-random hex. Unguessable; IS the grant. */
+    token: string;
+    /** Typed scope object (decision 6). */
+    scope: ShareScope;
+    /** Permissions delegated — a subset of what the issuer held when issuing (#1221). */
+    actions: string[];
+    /** What the delegation covers, in the policy resource shape (#1221). */
+    resources: ShareResource[];
+    /** Username of the issuing user — the delegator whose live authority bounds the share (#1222). */
+    createdBy: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 expiry, or null = until cancelled (decision 4). */
+    expiresAt: string | null;
+    /** ISO 8601 revocation timestamp — record retained for audit (decision 5). */
+    revokedAt?: string;
+    /**
+     * The owner's own note for a vault link, e.g. "For Dr Smith, October"
+     * (#1388). Shown to the owner only: never in a log or an audit record.
+     */
+    label?: string;
+    /** How many times a vault link has been used (#1388). */
+    visitCount?: number;
+    /** The most recent visits through a vault link, newest first, for its owner (#1388). */
+    visits?: ShareVisit[];
+    /**
+     * For a link to an encrypted vault (#1388): the public half of the link's
+     * key pair, made in the owner's browser. The server locks the link's pages
+     * and files for it and can never open them; the private half is in the
+     * link after `#` and never reaches the server.
+     */
+    lockedFor?: import('../utils/shareLockbox.js').LinkPublicKey;
+}
+/**
+ * One visit through a vault link, as its owner sees it (#1388): when, and
+ * what was opened. The audit trail keeps the full record, with the address.
+ */
+export interface ShareVisit {
+    at: string;
+    /** The page opened, by uuid. */
+    page?: string;
+    /** The file opened, by id. */
+    file?: string;
+    /** The link's page list was opened. */
+    list?: true;
+}
+/** A page admitted to a share scope, with fields for a search-result-style listing. */
+export interface SharePageEntry {
+    name: string;
+    title?: string;
+    uuid?: string;
+    /** System category (falls back to user category) for the chip row. */
+    category?: string;
+    /** User keywords for the chip row. */
+    keywords?: string[];
+    /** Content snippet (same generator as search results). */
+    excerpt?: string;
+    /** ISO 8601 last-modified timestamp. */
+    lastModified?: string;
+}

package/lib/src/types/Share.js

@@ -0,0 +1,81 @@
+import { parsePrivatePageName } from '../utils/privateStorePath.js';
+/** What a share delegates when the issuer asks for nothing more: read-only. */
+export const DEFAULT_SHARE_ACTIONS = ['page-read', 'asset-read'];
+/** Reserved keyword excluding content from every share (decision 1). */
+export const OWNER_ONLY_KEYWORD = 'owner-only';
+/** The prefix of the keyword pattern grammar a share resource speaks. */
+const KEYWORD_PATTERN = 'keyword:';
+/** `vault:{owner}/{vault}` — every current page in the vault (#1388). */
+const VAULT_PATTERN = 'vault:';
+/** `vault-page:{owner}/{vault}/{uuid}` — one page in the vault (#1388). */
+const VAULT_PAGE_PATTERN = 'vault-page:';
+/**
+ * Does a share cover a resource of `type` carrying `keywords`?
+ *
+ * The single reader of the `keyword:<name>` grammar. The evaluator asks it
+ * about a page's user-keywords; the share routes ask it about a media item's
+ * EXIF/XMP keywords. A pattern this function does not understand covers
+ * nothing — an unknown grammar is a refusal, never a wildcard — and content
+ * carrying `owner-only` is never covered, whatever else it carries.
+ */
+export function shareCoversResource(resources, type, keywords) {
+    if (keywords.includes(OWNER_ONLY_KEYWORD))
+        return false;
+    return resources.some((r) => r.type === type &&
+        r.pattern.startsWith(KEYWORD_PATTERN) &&
+        keywords.includes(r.pattern.slice(KEYWORD_PATTERN.length)));
+}
+/**
+ * Does a share name the vault `owner/vault` at all — whole, or any page in it?
+ * The container half of a vault share: who may step into the vault. Which
+ * pages it may then read is {@link shareCoversVaultPage}.
+ */
+export function shareNamesVault(resources, owner, vault) {
+    const whole = `${VAULT_PATTERN}${owner}/${vault}`;
+    const pagePrefix = `${VAULT_PAGE_PATTERN}${owner}/${vault}/`;
+    return resources.some((r) => r.type === 'page' && (r.pattern === whole || r.pattern.startsWith(pagePrefix)));
+}
+/**
+ * Does a share cover this page? The one rule both page doors ask (the decider
+ * and the list filter): a page in a vault by its uuid or its whole vault
+ * (#1388), any other page by its user-keywords.
+ */
+export function shareCoversPage(resources, pageName, metadata) {
+    const vaultPage = parsePrivatePageName(pageName);
+    if (vaultPage)
+        return shareCoversVaultPage(resources, vaultPage.owner, vaultPage.store, metadata.uuid);
+    return shareCoversResource(resources, 'page', metadata['user-keywords'] ?? []);
+}
+/** The vault a vault link covers, read from its resources, or null for any other share (#1388). */
+export function vaultOfShare(resources) {
+    for (const r of resources) {
+        if (r.type !== 'page')
+            continue;
+        const rest = r.pattern.startsWith(VAULT_PATTERN) ? r.pattern.slice(VAULT_PATTERN.length)
+            : r.pattern.startsWith(VAULT_PAGE_PATTERN) ? r.pattern.slice(VAULT_PAGE_PATTERN.length) : null;
+        if (rest === null)
+            continue;
+        const [owner, vault] = rest.split('/');
+        if (owner && vault)
+            return { owner, vault };
+    }
+    return null;
+}
+/** Does a share cover the page `uuid` in the vault `owner/vault`? */
+export function shareCoversVaultPage(resources, owner, vault, uuid) {
+    const whole = `${VAULT_PATTERN}${owner}/${vault}`;
+    const one = uuid ? `${VAULT_PAGE_PATTERN}${owner}/${vault}/${uuid}` : null;
+    return resources.some((r) => r.type === 'page' && (r.pattern === whole || (one !== null && r.pattern === one)));
+}
+/** The resources a scope names, in the shape the evaluator matches. */
+export function resourcesForScope(scope) {
+    if (scope.kind === 'vault') {
+        if (scope.pages === null)
+            return [{ type: 'page', pattern: `${VAULT_PATTERN}${scope.owner}/${scope.vault}` }];
+        return scope.pages.map((uuid) => ({ type: 'page', pattern: `${VAULT_PAGE_PATTERN}${scope.owner}/${scope.vault}/${uuid}` }));
+    }
+    return [
+        { type: 'page', pattern: `keyword:${scope.keyword}` },
+        { type: 'media', pattern: `keyword:${scope.keyword}` }
+    ];
+}

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

@@ -0,0 +1,304 @@
+/**
+ * User type definitions for ngdpbase
+ *
+ * This module defines types for users, authentication, roles, and permissions
+ * used by UserManager and authorization systems.
+ */
+/**
+ * An item pinned to the user's My Links sidebar section. The shape is unified
+ * across wiki pages and arbitrary app-route bookmarks (e.g. /my/journal,
+ * /profile, /search?q=foo). `url` is the canonical identifier; `pageName` is
+ * carried for wiki pages so the rendering path can still use page-aware
+ * affordances when relevant.
+ *
+ * Legacy entries (`{pageName, title}` only, no `url`) are normalised at read
+ * time by normalizePinnedItem in src/utils/pinnedItems.ts.
+ */
+export interface PinnedItem {
+    url: string;
+    title: string;
+    pageName?: string;
+    pinnedAt?: string;
+}
+/**
+ * @deprecated Use PinnedItem. Kept as an alias for back-compat with callers
+ * that only handle wiki-page pins.
+ */
+export type PinnedPage = PinnedItem;
+/**
+ * User preferences
+ *
+ * User-specific settings and preferences.
+ */
+export interface UserPreferences {
+    /** Editor smart pairs (auto-close brackets, quotes) */
+    'editor.plain.smartpairs'?: boolean;
+    /** Editor auto-indent */
+    'editor.autoindent'?: boolean;
+    /** Show line numbers in editor */
+    'editor.linenumbers'?: boolean;
+    /** Editor theme (light, dark, etc.) */
+    'editor.theme'?: string;
+    /** Display page size for lists */
+    'display.pagesize'?: string;
+    /** Show tooltips */
+    'display.tooltips'?: boolean;
+    /** Reader mode enabled */
+    'display.readermode'?: boolean;
+    /** Date format (iso, us, eu, etc.) */
+    'display.dateformat'?: string;
+    /** Timezone */
+    timezone?: string;
+    /** Language/locale */
+    locale?: string;
+    /** Items pinned to the My Links sidebar section (wiki pages and app-route URLs) */
+    'nav.pinnedPages'?: PinnedItem[];
+    /** Additional custom preferences */
+    [key: string]: unknown;
+}
+/**
+ * User object
+ *
+ * Complete user record stored in the user provider.
+ */
+export interface User {
+    /** Username (unique identifier for login) */
+    username: string;
+    /** Email address */
+    email: string;
+    /** Display name (full name) */
+    displayName: string;
+    /** Hashed password (SHA-256 or bcrypt) */
+    password: string;
+    /**
+     * @deprecated since #617 iteration 3b. Role membership is now stored
+     * canonically as OrganizationRole records owned by `RoleManager`; resolve
+     * a user's roles via `RoleManager.resolveUserRoles(username)`. The field
+     * is retained as optional for backwards compatibility while in-flight
+     * `users.json` files still carry it; the `strip-user-roles.ts` migration
+     * removes it. New code MUST NOT read or write this field directly.
+     */
+    roles?: string[];
+    /** Whether user account is active */
+    isActive: boolean;
+    /** Whether user is system user */
+    isSystem: boolean;
+    /** Whether user is external (LDAP, OAuth) */
+    isExternal: boolean;
+    /**
+     * A test account (#1805): it holds test or synthetic data, never real data,
+     * so a site can keep the two apart by account and show which is which.
+     *
+     * An attribute, not a role — it grants nothing and no policy reads it. Set
+     * by an administrator (`user-create` / `user-edit`), marked in the admin
+     * user list, shown to the signed-in person as a banner, and handed to the
+     * host as `userContext.isTest` and the OIDC `test_account` claim, so the
+     * host decides what a test account may do.
+     *
+     * Optional in storage only: an account saved before the flag existed has
+     * none. Every read through UserManager returns it as a boolean, `false`
+     * when absent.
+     */
+    isTest?: boolean;
+    /**
+     * Freeze this account's identity against self-service change (#1029).
+     *
+     * For a shared account whose credentials are published — a demo login, say —
+     * letting the holder edit their own identity hands the account away:
+     *
+     * - **password** — the first visitor to change it locks out every other
+     *   visitor and makes the published credential wrong.
+     * - **email** — worse, and the reason this covers more than the password.
+     *   Magic-link login resolves an account by email address
+     *   (`MagicLinkAuthProvider.getUserByEmail`), so a visitor who repoints the
+     *   address at their own inbox can magic-link back in indefinitely. The
+     *   password lock alone would not have stopped them.
+     * - **displayName** — defacement on a public instance.
+     *
+     * Preferences, avatar and pinned links stay editable: the point is to let a
+     * visitor drive the account, not to freeze it.
+     *
+     * Blocks the `/profile` path only. An administrator can still change any of
+     * it through `/admin/users/<name>/edit`, which requires `user-edit`, so the
+     * account is never unrecoverable.
+     *
+     * Distinct from `isSystem`, which means "cannot be deleted" and is set on
+     * `admin` — an account that must keep self-service password change.
+     */
+    profileLocked?: boolean;
+    /**
+     * Raised on every password change (#1482). A session stamped with an older
+     * value is signed out on its next request. See `utils/sessionGeneration`.
+     */
+    sessionGeneration?: number;
+    /** When the password last changed, ISO 8601 (#1592); written only by setPassword(). */
+    passwordChangedAt?: string;
+    /** Account creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** Last login timestamp (ISO 8601) */
+    lastLogin?: string;
+    /** Total login count */
+    loginCount: number;
+    /** User preferences */
+    preferences: UserPreferences;
+    /** Profile picture URL or data */
+    avatar?: string;
+    /** Wiki page name for this user's profile page */
+    profilePage?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /**
+     * Allowed authentication methods for this user.
+     * If absent, the user may use any method enabled at the system level.
+     * If present, only the listed provider IDs are accepted (e.g. ["oidc:google", "password"]).
+     * Useful for ensuring admin accounts can always use password as an emergency fallback.
+     */
+    allowedAuthMethods?: string[];
+}
+/**
+ * User creation data
+ *
+ * Data required to create a new user (no password hash yet).
+ */
+export interface UserCreateData {
+    /** Username (unique) */
+    username: string;
+    /** Email address */
+    email: string;
+    /** Display name */
+    displayName: string;
+    /** Plain text password (will be hashed) */
+    password: string;
+    /** Initial roles */
+    roles?: string[];
+    /** Whether account starts active */
+    isActive?: boolean;
+    /** User preferences */
+    preferences?: Partial<UserPreferences>;
+}
+/**
+ * User update data
+ *
+ * Partial user data for updates (all fields optional).
+ */
+export interface UserUpdateData {
+    /** Email address */
+    email?: string;
+    /** Display name */
+    displayName?: string;
+    /** New plain text password (will be hashed) */
+    password?: string;
+    /** Updated roles */
+    roles?: string[];
+    /** Active status */
+    isActive?: boolean;
+    /** Updated preferences */
+    preferences?: Partial<UserPreferences>;
+    /** Avatar */
+    avatar?: string;
+    /** Metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * User session data
+ *
+ * Active session information stored by session manager.
+ */
+export interface UserSession {
+    /** Session ID (unique) */
+    sessionId: string;
+    /** Username */
+    username: string;
+    /** User ID (username or external ID) */
+    userId: string;
+    /** Session creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** Session expiration timestamp (ISO 8601) */
+    expiresAt: string;
+    /** Last activity timestamp (ISO 8601) */
+    lastActivity: string;
+    /** Client IP address */
+    ipAddress?: string;
+    /** User agent string */
+    userAgent?: string;
+    /** Additional session data */
+    data?: Record<string, unknown>;
+}
+/**
+ * User authentication result
+ *
+ * Result of authentication attempt.
+ */
+export interface AuthResult {
+    /** Whether authentication succeeded */
+    success: boolean;
+    /** User object if successful */
+    user?: User;
+    /** Session ID if successful */
+    sessionId?: string;
+    /** Error message if failed */
+    error?: string;
+    /** Error code (invalid_credentials, account_disabled, etc.) */
+    errorCode?: string;
+}
+/**
+ * User role definition
+ *
+ * Defines a role and its permissions.
+ */
+export interface Role {
+    /** Role name (unique identifier) */
+    name: string;
+    /** Display name */
+    displayName: string;
+    /** Role description */
+    description?: string;
+    /** Permissions granted by this role */
+    permissions: string[];
+    /** Whether this is a system role (cannot be deleted) */
+    isSystem: boolean;
+    /** Parent roles (inheritance) */
+    inherits?: string[];
+}
+/**
+ * User permission
+ *
+ * Defines a specific permission.
+ */
+export interface Permission {
+    /** Permission name (unique identifier) */
+    name: string;
+    /** Display name */
+    displayName: string;
+    /** Permission description */
+    description?: string;
+    /** Resource this permission applies to */
+    resource: string;
+    /** Action allowed (view, edit, delete, etc.) */
+    action: string;
+    /** Whether this is a system permission */
+    isSystem: boolean;
+}
+/**
+ * User profile
+ *
+ * Public user profile (safe to expose to other users).
+ */
+export interface UserProfile {
+    /** Username */
+    username: string;
+    /** Display name */
+    displayName: string;
+    /** Email (may be hidden based on privacy settings) */
+    email?: string;
+    /** Avatar */
+    avatar?: string;
+    /** Roles (may be filtered based on permissions) */
+    roles?: string[];
+    /** Whether user is active */
+    isActive: boolean;
+    /** Account creation date */
+    createdAt: string;
+    /** Last login (may be hidden) */
+    lastLogin?: string;
+}