@plumix/core 0.1.0

package/dist/admin-bar/styles.d.ts

@@ -0,0 +1,5 @@
+export declare const ADMIN_BAR_CSS: string;
+export declare const ADMIN_BAR_BODY_OFFSET_CSS: string;
+export declare const ADMIN_BAR_SIGNOUT_SCRIPT = "\n(function () {\n  var sel = \"[data-plumix-signout]\";\n  document.addEventListener(\"click\", function (event) {\n    var node = event.target;\n    var trigger = node && node.closest ? node.closest(sel) : null;\n    if (!trigger) return;\n    event.preventDefault();\n    trigger.disabled = true;\n    fetch(\"/_plumix/auth/signout\", {\n      method: \"POST\",\n      headers: { \"X-Plumix-Request\": \"1\" },\n      credentials: \"same-origin\",\n    })\n      .then(function (res) { return res.ok ? res.json() : null; })\n      .then(function (data) {\n        var to = data && data.redirectTo ? data.redirectTo : location.pathname;\n        location.assign(to);\n      })\n      .catch(function () { location.reload(); });\n  });\n})();\n";
+export declare const ADMIN_BAR_NOSCRIPT_CSS = "[data-plumix-signout]{display:none}";
+//# sourceMappingURL=styles.d.ts.map

package/dist/admin-bar/styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../../src/admin-bar/styles.ts"],"names":[],"mappings":"AAuBA,eAAO,MAAM,aAAa,QA+LzB,CAAC;AAEF,eAAO,MAAM,yBAAyB,QASrC,CAAC;AAOF,eAAO,MAAM,wBAAwB,8uBAsBpC,CAAC;AAIF,eAAO,MAAM,sBAAsB,wCAAwC,CAAC"}

package/dist/admin-bar/styles.js

@@ -0,0 +1,252 @@
+// Inline CSS for the admin bar — emitted once per page render via a
+// `<style>` tag inside the bar. All selectors scoped under a single stable
+// `.plumix-admin-bar` class so the theme's own CSS is untouchable. Font
+// stack covers Latin / Cyrillic / Arabic / CJK without a webfont request
+// (see [[plumix-admin-bar/issue-668]] for rationale). Multi-script glyph
+// rendering falls through `system-ui` to the OS UI font; missing-glyph
+// fallback is the browser's responsibility.
+// No-op tag — the tooling marker that lets vscode-styled-components +
+// stylelint syntax-highlight + lint the CSS source. CSS Modules don't fit
+// because the bar is built with tsc-only and emits its CSS inline in the
+// SSR response, not as a separate stylesheet request.
+function css(strings, ...values) {
+    let out = strings[0] ?? "";
+    for (let i = 0; i < values.length; i++) {
+        out += values[i] + (strings[i + 1] ?? "");
+    }
+    return out;
+}
+export const ADMIN_BAR_CSS = css `
+  .plumix-admin-bar {
+    position: fixed;
+    top: 0;
+    left: 0;
+    right: 0;
+    z-index: var(--plumix-admin-bar-z-index, 99999);
+    height: 36px;
+    background: #1d2327;
+    color: #fff;
+    font-family:
+      system-ui,
+      -apple-system,
+      "Segoe UI",
+      Roboto,
+      "Noto Sans",
+      "Noto Sans Arabic",
+      "Noto Sans SC",
+      "Helvetica Neue",
+      Arial,
+      sans-serif;
+    font-size: 13px;
+    line-height: 36px;
+    box-sizing: border-box;
+  }
+  .plumix-admin-bar *,
+  .plumix-admin-bar *::before,
+  .plumix-admin-bar *::after {
+    box-sizing: inherit;
+  }
+  .plumix-admin-bar nav {
+    display: flex;
+    align-items: stretch;
+    height: 100%;
+    padding: 0 12px;
+  }
+  .plumix-admin-bar nav > ul {
+    flex: 1;
+  }
+  .plumix-admin-bar ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    align-items: stretch;
+    gap: 4px;
+  }
+  .plumix-admin-bar li {
+    display: flex;
+    align-items: stretch;
+    max-width: 240px;
+  }
+  .plumix-admin-bar__end {
+    margin-inline-start: auto;
+  }
+  .plumix-admin-bar a,
+  .plumix-admin-bar summary,
+  .plumix-admin-bar span,
+  .plumix-admin-bar button {
+    color: #fff;
+    text-decoration: none;
+    padding: 0 10px;
+    display: inline-flex;
+    align-items: center;
+    cursor: pointer;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    max-width: 100%;
+  }
+  .plumix-admin-bar button {
+    appearance: none;
+    background: none;
+    border: 0;
+    font: inherit;
+    width: 100%;
+    text-align: start;
+  }
+  .plumix-admin-bar a:hover,
+  .plumix-admin-bar summary:hover,
+  .plumix-admin-bar button:hover {
+    background: #2c3338;
+  }
+  /* Specificity must beat \`.plumix-admin-bar span\` (0,1,1), which would
+     otherwise re-show the disc and restore its text padding. */
+  .plumix-admin-bar span.plumix-admin-bar__avatar {
+    display: none;
+    width: 24px;
+    height: 24px;
+    padding: 0;
+    border-radius: 50%;
+    background: #2c3338;
+    font-size: 12px;
+    font-weight: 600;
+    line-height: 1;
+    align-items: center;
+    justify-content: center;
+    flex: 0 0 auto;
+  }
+  .plumix-admin-bar details {
+    position: relative;
+    display: flex;
+  }
+  .plumix-admin-bar summary {
+    list-style: none;
+  }
+  .plumix-admin-bar summary::-webkit-details-marker {
+    display: none;
+  }
+  .plumix-admin-bar summary::after {
+    content: " \\25BE";
+    opacity: 0.7;
+    margin-inline-start: 4px;
+  }
+  .plumix-admin-bar details[open] > summary {
+    background: #2c3338;
+  }
+  .plumix-admin-bar details > ul {
+    position: absolute;
+    top: 100%;
+    left: 0;
+    flex-direction: column;
+    background: #2c3338;
+    min-width: 200px;
+    padding: 4px 0;
+    box-shadow: 0 2px 6px rgba(0, 0, 0, 0.25);
+    z-index: 1;
+  }
+  .plumix-admin-bar details > ul > li {
+    max-width: 100%;
+  }
+  .plumix-admin-bar details > ul a,
+  .plumix-admin-bar details > ul button {
+    display: block;
+    padding: 6px 12px;
+    line-height: 1.4;
+  }
+  /* The account menu sits at the row's end — open its dropdown toward the
+     inline-start so it can't spill off the viewport edge. */
+  .plumix-admin-bar__end details > ul {
+    left: auto;
+    right: 0;
+  }
+  .plumix-admin-bar[dir="rtl"] nav {
+    flex-direction: row-reverse;
+  }
+  .plumix-admin-bar[dir="rtl"] details > ul {
+    left: auto;
+    right: 0;
+  }
+  .plumix-admin-bar[dir="rtl"] .plumix-admin-bar__end details > ul {
+    right: auto;
+    left: 0;
+  }
+  /* Mobile: keep the bar visible (WP does too) but grow it for touch — a
+     taller strip, an avatar disc in place of the long email, and roomier
+     dropdown rows. Submenus already tap-to-open via native <details>. */
+  @media (max-width: 639px) {
+    .plumix-admin-bar {
+      height: 46px;
+      line-height: 46px;
+    }
+    .plumix-admin-bar nav {
+      padding: 0 4px;
+    }
+    .plumix-admin-bar a,
+    .plumix-admin-bar summary,
+    .plumix-admin-bar span,
+    .plumix-admin-bar button {
+      padding: 0 8px;
+    }
+    .plumix-admin-bar li {
+      max-width: 40vw;
+    }
+    .plumix-admin-bar details > ul {
+      top: 46px;
+    }
+    .plumix-admin-bar details > ul a,
+    .plumix-admin-bar details > ul button {
+      padding: 10px 14px;
+    }
+    .plumix-admin-bar span.plumix-admin-bar__avatar {
+      display: inline-flex;
+    }
+    .plumix-admin-bar__end > details > summary > bdi {
+      display: none;
+    }
+    .plumix-admin-bar__end > details > summary {
+      padding-inline: 6px;
+    }
+  }
+`;
+export const ADMIN_BAR_BODY_OFFSET_CSS = css `
+  body {
+    padding-top: 36px;
+  }
+  @media (max-width: 639px) {
+    body {
+      padding-top: 46px;
+    }
+  }
+`;
+// Inline sign-out island — the bar's one concession to JS. The signout
+// endpoint is CSRF-gated on the custom `X-Plumix-Request` header (a plain
+// link/form can't set it) and answers with JSON, so a button + fetch is
+// the minimal wiring. `redirectTo` is honored for external-IdP logout;
+// otherwise the current page reloads, now unauthenticated (no bar).
+export const ADMIN_BAR_SIGNOUT_SCRIPT = `
+(function () {
+  var sel = "[data-plumix-signout]";
+  document.addEventListener("click", function (event) {
+    var node = event.target;
+    var trigger = node && node.closest ? node.closest(sel) : null;
+    if (!trigger) return;
+    event.preventDefault();
+    trigger.disabled = true;
+    fetch("/_plumix/auth/signout", {
+      method: "POST",
+      headers: { "X-Plumix-Request": "1" },
+      credentials: "same-origin",
+    })
+      .then(function (res) { return res.ok ? res.json() : null; })
+      .then(function (data) {
+        var to = data && data.redirectTo ? data.redirectTo : location.pathname;
+        location.assign(to);
+      })
+      .catch(function () { location.reload(); });
+  });
+})();
+`;
+// With JS off the sign-out button can't do anything (the endpoint needs a
+// fetch with the CSRF header) — hide it rather than show a dead control.
+export const ADMIN_BAR_NOSCRIPT_CSS = "[data-plumix-signout]{display:none}";
+//# sourceMappingURL=styles.js.map

package/dist/admin-bar/styles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.js","sourceRoot":"","sources":["../../src/admin-bar/styles.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,2EAA2E;AAC3E,wEAAwE;AACxE,yEAAyE;AACzE,yEAAyE;AACzE,uEAAuE;AACvE,4CAA4C;AAE5C,sEAAsE;AACtE,0EAA0E;AAC1E,yEAAyE;AACzE,sDAAsD;AACtD,SAAS,GAAG,CACV,OAA6B,EAC7B,GAAG,MAAyB;IAE5B,IAAI,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+L/B,CAAC;AAEF,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAA;;;;;;;;;CAS3C,CAAC;AAEF,uEAAuE;AACvE,0EAA0E;AAC1E,wEAAwE;AACxE,uEAAuE;AACvE,oEAAoE;AACpE,MAAM,CAAC,MAAM,wBAAwB,GAAG;;;;;;;;;;;;;;;;;;;;;;CAsBvC,CAAC;AAEF,0EAA0E;AAC1E,yEAAyE;AACzE,MAAM,CAAC,MAAM,sBAAsB,GAAG,qCAAqC,CAAC"}

package/dist/admin-bar/types.d.ts

@@ -0,0 +1,64 @@
+import type { AuthenticatedUser, AuthNamespace } from "../context/app.js";
+import type { RegisteredEntryType } from "../plugin/manifest.js";
+import type { ResolvedEntity } from "../route/current.ts";
+import type { BarLocale } from "./i18n.js";
+export declare const ADMIN_BAR_GROUPS: readonly ["primary", "secondary", "+new", "account", "root"];
+type AdminBarGroup = (typeof ADMIN_BAR_GROUPS)[number];
+export interface AdminBarNode {
+    readonly id: string;
+    readonly title: string;
+    readonly href?: string;
+    readonly group: AdminBarGroup;
+    readonly parent?: string;
+    readonly position?: number;
+    /**
+     * Marks a node as a client action rather than a navigation link. The
+     * bar is otherwise zero-JS server chrome; `"signout"` is the single
+     * exception, rendered as a `<button>` wired to the inline sign-out
+     * island instead of an `<a>`/`<span>`.
+     */
+    readonly action?: "signout";
+}
+export interface AdminBarTreeNode extends AdminBarNode {
+    readonly children: readonly AdminBarTreeNode[];
+}
+export interface BarRenderContext {
+    readonly user: AuthenticatedUser;
+    readonly queriedEntry: ResolvedEntity | null;
+    /**
+     * Pre-resolved details for `queriedEntry.kind === "entry"` — the
+     * entry's registered type and `authorId`. Populated by the renderer
+     * before the bar collects nodes so sync filter handlers (e.g. the
+     * core edit-this contributor) can check capabilities without async
+     * DB lookups.
+     */
+    readonly queriedEntryDetails?: {
+        readonly type: string;
+        readonly authorId: number;
+    };
+    readonly request: Request;
+    readonly siteName: string;
+    readonly auth: AuthNamespace;
+    /**
+     * Registered entry types in registration order — supplied by the renderer
+     * from `app.plugins.entryTypes` so the `+ New` contributor can populate
+     * its child menu without a separate discovery API.
+     */
+    readonly entryTypes: ReadonlyMap<string, RegisteredEntryType>;
+    /**
+     * Resolved bar locale (WP-style — read from `user.meta.locale`, falls
+     * back to `en` for unrecognised values). Core contributors translate
+     * their literals through this; plugin contributors stay responsible
+     * for their own catalogs and pass already-translated `title` strings.
+     */
+    readonly locale: BarLocale;
+    /** Text direction for the bar element — `rtl` for `ar`, `ltr` elsewhere. */
+    readonly direction: "ltr" | "rtl";
+}
+declare module "../hooks/types.js" {
+    interface FilterRegistry {
+        "admin_bar:nodes": (nodes: readonly AdminBarNode[], ctx: BarRenderContext) => readonly AdminBarNode[];
+    }
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/admin-bar/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/admin-bar/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,eAAO,MAAM,gBAAgB,8DAMnB,CAAC;AAEX,KAAK,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE;QAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC9D;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,KAAK,CAAC;CACnC;AAED,OAAO,QAAQ,mBAAmB,CAAC;IACjC,UAAU,cAAc;QACtB,iBAAiB,EAAE,CACjB,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,GAAG,EAAE,gBAAgB,KAClB,SAAS,YAAY,EAAE,CAAC;KAC9B;CACF"}

package/dist/admin-bar/types.js

@@ -0,0 +1,8 @@
+export const ADMIN_BAR_GROUPS = [
+    "primary",
+    "secondary",
+    "+new",
+    "account",
+    "root",
+];
+//# sourceMappingURL=types.js.map

package/dist/admin-bar/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/admin-bar/types.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,SAAS;IACT,WAAW;IACX,MAAM;IACN,SAAS;IACT,MAAM;CACE,CAAC"}

package/dist/auth/api-tokens.d.ts

@@ -0,0 +1,84 @@
+import type { Db } from "../context/app.js";
+import type { ApiToken } from "../db/schema/api_tokens.js";
+import type { User } from "../db/schema/users.js";
+export declare const API_TOKEN_PREFIX = "pl_pat_";
+export interface MintedApiToken {
+    /** Raw token to ship to the client exactly once. Never persisted. */
+    readonly secret: string;
+    /** The persisted row, sans the secret (already in DB at return time). */
+    readonly row: ApiToken;
+}
+export interface CreateApiTokenInput {
+    readonly userId: number;
+    readonly name: string;
+    /**
+     * Token expiry. Pass `null` for never-expires (long-lived CI / MCP
+     * server tokens); the admin form nudges towards a TTL but allows
+     * opting out. The hot path treats `null` as "no expiry check"; only
+     * the lookup's `revokedAt` and a manual revocation can kill it.
+     */
+    readonly expiresAt: Date | null;
+    /**
+     * Capability scope whitelist. null = unrestricted (inherits the
+     * user's role caps); non-null = the token's effective caps are the
+     * intersection of this list with the user's role caps. See
+     * `db/schema/api_tokens.ts` for the full rationale.
+     */
+    readonly scopes?: readonly string[] | null;
+}
+/**
+ * Mint a new personal access token.
+ *
+ * Generates `pl_pat_<random>`, stores the SHA-256 hash + a short
+ * recognisable prefix fragment, and returns both the secret (caller
+ * shows once, never recoverable) and the persisted row.
+ *
+ * Concurrent calls have negligible collision risk (256 bits of
+ * randomness) but the `id` column is the primary key, so a duplicate
+ * would surface as a unique-constraint error rather than silent
+ * corruption.
+ */
+export declare function createApiToken(db: Db, input: CreateApiTokenInput): Promise<MintedApiToken>;
+interface ValidatedApiToken {
+    readonly user: User;
+    readonly token: ApiToken;
+}
+/**
+ * Validate a raw `Authorization: Bearer pl_pat_…` token.
+ *
+ * Returns the user + token row when:
+ *   - the token's prefix matches `pl_pat_`,
+ *   - the row exists,
+ *   - the row isn't revoked,
+ *   - the row hasn't expired (or has no expiry),
+ *   - the linked user isn't disabled.
+ *
+ * Returns null on any miss — the authenticator caller maps null to
+ * "no auth on this request" (which the dispatcher then turns into a
+ * 401 for protected routes). The specific reason is logged but not
+ * surfaced to the client; an attacker probing tokens learns nothing
+ * beyond "this token doesn't authenticate."
+ *
+ * On success, updates `lastUsedAt` synchronously before returning.
+ * One indexed UPDATE per authed request — the cost is small and the
+ * race is benign (concurrent updates last-write-wins on a
+ * timestamp). If/when the hot-path latency budget tightens this can
+ * move to `ctx.after()` (worker-tail / waitUntil); v0.1.0 keeps it
+ * simple and synchronous.
+ */
+export declare function validateApiToken(db: Db, rawToken: string): Promise<ValidatedApiToken | null>;
+/**
+ * Soft-delete a token by setting `revokedAt`. Idempotent — calling on
+ * an already-revoked token is a no-op (the WHERE clause includes
+ * `IS NULL` so the second call updates zero rows, which is fine).
+ *
+ * Self-scoped via the `userId` predicate; cross-user attempts return
+ * `false` (no row matched). The caller — a self-scoped RPC procedure
+ * — should map false to NOT_FOUND.
+ */
+export declare function revokeApiToken(db: Db, input: {
+    id: string;
+    userId: number;
+}): Promise<boolean>;
+export {};
+//# sourceMappingURL=api-tokens.d.ts.map

package/dist/auth/api-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-tokens.d.ts","sourceRoot":"","sources":["../../src/auth/api-tokens.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAYlD,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAO1C,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CAC5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,EAAE,EACN,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,cAAc,CAAC,CAuBzB;AAED,UAAU,iBAAiB;IACzB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,EAAE,EACN,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAiCnC;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,EAAE,EACN,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC,OAAO,CAAC,OAAO,CAAC,CAalB"}

package/dist/auth/api-tokens.js

@@ -0,0 +1,121 @@
+import { encodeBase64urlNoPadding } from "@oslojs/encoding";
+import { and, eq, gt, isNull, or } from "../db/index.js";
+import { apiTokens } from "../db/schema/api_tokens.js";
+import { users } from "../db/schema/users.js";
+import { hashToken } from "./tokens.js";
+// Personal-access-token format: `pl_pat_<32 random bytes, base64url>`.
+// The prefix is recognizable on grep/log, signals "this is a Plumix
+// PAT", and makes accidental commits to git easier to spot — same
+// design as GitHub's `ghp_` / `gho_` and NPM's `npm_`. The 32-byte
+// random suffix gives 256 bits of entropy, well past the 120-bit
+// Copenhagen Book floor.
+export const API_TOKEN_PREFIX = "pl_pat_";
+const API_TOKEN_BODY_BYTES = 32;
+// Length of the displayed `prefix` field — `pl_pat_` plus the first 4
+// chars of the random body. Short enough to fit in a list cell, long
+// enough to disambiguate users' own tokens at a glance.
+const PREFIX_DISPLAY_BODY_CHARS = 4;
+/**
+ * Mint a new personal access token.
+ *
+ * Generates `pl_pat_<random>`, stores the SHA-256 hash + a short
+ * recognisable prefix fragment, and returns both the secret (caller
+ * shows once, never recoverable) and the persisted row.
+ *
+ * Concurrent calls have negligible collision risk (256 bits of
+ * randomness) but the `id` column is the primary key, so a duplicate
+ * would surface as a unique-constraint error rather than silent
+ * corruption.
+ */
+export async function createApiToken(db, input) {
+    const secret = generateApiTokenSecret();
+    const id = await hashToken(secret);
+    const prefix = secret.slice(0, API_TOKEN_PREFIX.length + PREFIX_DISPLAY_BODY_CHARS);
+    const [row] = await db
+        .insert(apiTokens)
+        .values({
+        id,
+        userId: input.userId,
+        name: input.name,
+        prefix,
+        expiresAt: input.expiresAt,
+        scopes: input.scopes ?? null,
+    })
+        .returning();
+    // eslint-disable-next-line no-restricted-syntax -- defensive driver-regression guard; migrate alongside auth errors in PR 2 (#234)
+    if (!row)
+        throw new Error("createApiToken: insert returned no row");
+    return { secret, row };
+}
+/**
+ * Validate a raw `Authorization: Bearer pl_pat_…` token.
+ *
+ * Returns the user + token row when:
+ *   - the token's prefix matches `pl_pat_`,
+ *   - the row exists,
+ *   - the row isn't revoked,
+ *   - the row hasn't expired (or has no expiry),
+ *   - the linked user isn't disabled.
+ *
+ * Returns null on any miss — the authenticator caller maps null to
+ * "no auth on this request" (which the dispatcher then turns into a
+ * 401 for protected routes). The specific reason is logged but not
+ * surfaced to the client; an attacker probing tokens learns nothing
+ * beyond "this token doesn't authenticate."
+ *
+ * On success, updates `lastUsedAt` synchronously before returning.
+ * One indexed UPDATE per authed request — the cost is small and the
+ * race is benign (concurrent updates last-write-wins on a
+ * timestamp). If/when the hot-path latency budget tightens this can
+ * move to `ctx.after()` (worker-tail / waitUntil); v0.1.0 keeps it
+ * simple and synchronous.
+ */
+export async function validateApiToken(db, rawToken) {
+    if (!rawToken.startsWith(API_TOKEN_PREFIX))
+        return null;
+    const id = await hashToken(rawToken);
+    const now = new Date();
+    // Single statement: row exists AND not revoked AND (no expiry OR
+    // not yet expired). Hits the PK index for the lookup; the WHERE
+    // additions are constant-time per row.
+    const row = await db
+        .select({ token: apiTokens, user: users })
+        .from(apiTokens)
+        .innerJoin(users, eq(users.id, apiTokens.userId))
+        .where(and(eq(apiTokens.id, id), isNull(apiTokens.revokedAt), or(isNull(apiTokens.expiresAt), gt(apiTokens.expiresAt, now))))
+        .get();
+    if (!row)
+        return null;
+    if (row.user.disabledAt)
+        return null;
+    // Update lastUsedAt non-blocking on the request hot path; failure
+    // here doesn't affect auth (the user is already authenticated).
+    await db
+        .update(apiTokens)
+        .set({ lastUsedAt: now })
+        .where(eq(apiTokens.id, id));
+    return { user: row.user, token: row.token };
+}
+/**
+ * Soft-delete a token by setting `revokedAt`. Idempotent — calling on
+ * an already-revoked token is a no-op (the WHERE clause includes
+ * `IS NULL` so the second call updates zero rows, which is fine).
+ *
+ * Self-scoped via the `userId` predicate; cross-user attempts return
+ * `false` (no row matched). The caller — a self-scoped RPC procedure
+ * — should map false to NOT_FOUND.
+ */
+export async function revokeApiToken(db, input) {
+    const result = await db
+        .update(apiTokens)
+        .set({ revokedAt: new Date() })
+        .where(and(eq(apiTokens.id, input.id), eq(apiTokens.userId, input.userId), isNull(apiTokens.revokedAt)))
+        .returning({ id: apiTokens.id });
+    return result.length > 0;
+}
+function generateApiTokenSecret() {
+    const bytes = new Uint8Array(API_TOKEN_BODY_BYTES);
+    crypto.getRandomValues(bytes);
+    return `${API_TOKEN_PREFIX}${encodeBase64urlNoPadding(bytes)}`;
+}
+//# sourceMappingURL=api-tokens.js.map

package/dist/auth/api-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-tokens.js","sourceRoot":"","sources":["../../src/auth/api-tokens.ts"],"names":[],"mappings":"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"}

package/dist/auth/authenticator.d.ts

@@ -0,0 +1,109 @@
+import type { Db } from "../context/app.js";
+import type { User } from "../db/schema/users.js";
+/**
+ * Resolved auth on a request — the user plus any guard-specific
+ * narrowing of capabilities. Returned by `RequestAuthenticator`s.
+ *
+ * `tokenScopes`:
+ *   - `undefined` / `null` → unrestricted, the user's role caps apply
+ *     verbatim (session-cookie auth, IdP guards like cfAccess).
+ *   - `readonly string[]` → capability whitelist. The effective caps
+ *     are `tokenScopes ∩ roleCaps`, so a token can never escalate.
+ *     Used by API-token auth where the operator scoped the token at
+ *     mint time.
+ *
+ * `auth.can()` on `AppContext` is the single chokepoint that consults
+ * `tokenScopes` — every capability check in core + plugins reads
+ * through it, so adding a guard that returns scopes Just Works
+ * everywhere without scattered checks.
+ */
+export interface AuthResult {
+    readonly user: User;
+    readonly tokenScopes?: readonly string[] | null;
+}
+/**
+ * Decides who the user is on a given request — Laravel-style Guard.
+ *
+ * Default: read the session cookie, look up the row. Override at config
+ * time with anything that maps a request to an `AuthResult` (or null):
+ *
+ *   - `cfAccess({ teamDomain })` from `@plumix/runtime-cloudflare` —
+ *     validates the Cloudflare Access JWT header.
+ *   - `apiTokenAuthenticator()` — `Authorization: Bearer …` against
+ *     the hashed `api_tokens` table; surfaces per-token `scopes`.
+ *   - User-shipped enterprise SSO / custom guards: implement this
+ *     one-method interface, no plumix changes required.
+ *
+ * The contract is intentionally narrow:
+ *   - Returns `AuthResult | null`. `null` means "no auth on this
+ *     request" — the caller decides whether that's a 401 or anonymous
+ *     access.
+ *   - Throws on a malformed credential (bad signature, replay, etc.)
+ *     so the dispatcher can map to a typed error.
+ *   - No side effects: the authenticator does NOT mint sessions or
+ *     set cookies. Login flows do that. A guard only reads.
+ */
+export interface RequestAuthenticator {
+    authenticate(request: Request, db: Db): Promise<AuthResult | null>;
+    /**
+     * Optional. Where the user should land after signing out — surfaced
+     * to the admin client by `/_plumix/auth/signout` as `redirectTo`.
+     * Returning null (or omitting the method) keeps the default
+     * behaviour: clear the local session cookie and let the admin
+     * navigate to the login screen.
+     *
+     * Required for IdPs that maintain their own session (Cloudflare
+     * Access, SAML SP-initiated flows) — without redirecting to the
+     * IdP's logout endpoint, the next request still carries the IdP
+     * cookie/JWT and the user is silently re-signed-in.
+     *
+     * The returned URL must be either an absolute `https://` URL or a
+     * same-origin path beginning with `/`. Invalid or unsafe values are
+     * silently dropped at the dispatcher boundary so a malicious
+     * authenticator can't inject `javascript:` or protocol-relative
+     * redirect targets into the admin client.
+     */
+    signOutUrl?(): string | null;
+}
+/**
+ * Default authenticator — reads the `plumix_session` cookie, validates
+ * the row, returns the user. Same logic the dispatcher used inline
+ * before this contract existed; isolating it here makes it swappable.
+ *
+ * Returns no `tokenScopes` — a browser session inherits the full role
+ * caps. PAT-style scoping doesn't apply here.
+ */
+export declare function sessionAuthenticator(): RequestAuthenticator;
+/**
+ * Personal-access-token authenticator. Reads the
+ * `Authorization: Bearer pl_pat_…` header, hashes it, looks up the
+ * row in `api_tokens`, and bumps `lastUsedAt`. Used by CLIs / MCP
+ * servers / any non-browser client.
+ *
+ * Composed with `sessionAuthenticator()` by default (see
+ * `defaultAuthenticator()`) so a single plumix install supports both
+ * cookie-authed admin browsing AND bearer-authed API access without
+ * any operator config.
+ */
+export declare function apiTokenAuthenticator(): RequestAuthenticator;
+/**
+ * Compose multiple authenticators into a first-match-wins chain. The
+ * first one to return a non-null user decides the request. `signOutUrl`
+ * is taken from the first authenticator that exposes it — the chain is
+ * a list, and the head wins when both could speak.
+ *
+ * Used to wire the default plumix install: the cookie-session guard
+ * in front of the API-token guard, so browser requests resolve via
+ * the existing path and bearer-auth API clients don't need any
+ * operator config.
+ */
+export declare function chainAuthenticators(...authenticators: readonly RequestAuthenticator[]): RequestAuthenticator;
+/**
+ * Out-of-the-box authenticator: cookie-session + API token. Plumix
+ * uses this when `auth.authenticator` is omitted from config; the
+ * existing `sessionAuthenticator()` direct usage is preserved as the
+ * intentional "no API tokens" path for ops who want to disable
+ * bearer-auth at the runtime level.
+ */
+export declare function defaultAuthenticator(): RequestAuthenticator;
+//# sourceMappingURL=authenticator.d.ts.map