@cosmicdrift/kumiko-bundled-features 0.256.0 → 0.258.0

package/src/personal-access-tokens/__tests__/pat.integration.test.ts

@@ -55,6 +55,10 @@ import type { PatScopeConfig } from "../scopes";
 let stack: TestStack;
 let h: ReturnType<typeof makeSessionHelpers>;
 
+// `personal-access-tokens:query:mine` is now a paged handler — every caller
+// reads `response.rows` instead of a blank array (fw#2548 Teil B).
+type PatRowsEnvelope<T> = { readonly rows: readonly T[]; readonly nextCursor: string | null };
+
 const encryptionKey = randomBytes(32).toString("base64");
 const TENANT: TenantId = testTenantId(1);
 
@@ -183,7 +187,11 @@ describe("PAT auth", () => {
   test("revoked token → 401", async () => {
     const actor = await actorFor("revoked@example.com");
     const token = await mintToken(actor);
-    const rows = await stack.http.queryOk<Array<{ id: string }>>(PatQueries.mine, {}, actor);
+    const { rows } = await stack.http.queryOk<PatRowsEnvelope<{ id: string }>>(
+      PatQueries.mine,
+      {},
+      actor,
+    );
     const id = rows[0]?.id;
     expect(id).toBeDefined();
     await stack.http.writeOk(PatHandlers.revoke, { id }, actor);
@@ -195,8 +203,11 @@ describe("PAT auth", () => {
     const actor = await actorFor("expired@example.com");
     const token = await mintToken(actor);
     const past = Temporal.Now.instant().subtract({ hours: 1 });
-    const rows =
-      (await stack.http.queryOk<Array<{ id: string }>>(PatQueries.mine, {}, actor)) ?? [];
+    const { rows } = await stack.http.queryOk<PatRowsEnvelope<{ id: string }>>(
+      PatQueries.mine,
+      {},
+      actor,
+    );
     await updateMany(stack.db, apiTokenTable, { expiresAt: past }, { id: rows[0]?.id });
     const res = await h.authedPost("/api/query", token, { type: PatQueries.mine, payload: {} });
     expect(res.status).toBe(401);
@@ -245,7 +256,7 @@ describe("PAT with active KMS (#820): token name is userOwned PII", () => {
       const actor = await actorFor("kms-pat@example.com");
       const token = await mintToken(actor);
 
-      const rows = await stack.http.queryOk<Array<{ id: string; name: string }>>(
+      const { rows } = await stack.http.queryOk<PatRowsEnvelope<{ id: string; name: string }>>(
         PatQueries.mine,
         {},
         actor,
@@ -276,7 +287,11 @@ describe("PAT create: re-auth (#security)", () => {
       actor,
     );
     expect(err.httpStatus).toBeGreaterThanOrEqual(400);
-    const rows = await stack.http.queryOk<Array<{ id: string }>>(PatQueries.mine, {}, actor);
+    const { rows } = await stack.http.queryOk<PatRowsEnvelope<{ id: string }>>(
+      PatQueries.mine,
+      {},
+      actor,
+    );
     expect(rows).toHaveLength(0);
   });
 
@@ -288,18 +303,20 @@ describe("PAT create: re-auth (#security)", () => {
       actor,
     );
     expect(err.details).toMatchObject({ reason: PatErrors.reauthRequired });
-    const rows = await stack.http.queryOk<Array<{ id: string }>>(PatQueries.mine, {}, actor);
+    const { rows } = await stack.http.queryOk<PatRowsEnvelope<{ id: string }>>(
+      PatQueries.mine,
+      {},
+      actor,
+    );
     expect(rows).toHaveLength(0);
   });
 
   test("expiresInDays omitted → defaults to ~90 days, not never-expiring", async () => {
     const actor = await actorFor("reauth-expiry@example.com");
     await mintToken(actor);
-    const rows = await stack.http.queryOk<Array<{ id: string; expiresAt: string | null }>>(
-      PatQueries.mine,
-      {},
-      actor,
-    );
+    const { rows } = await stack.http.queryOk<
+      PatRowsEnvelope<{ id: string; expiresAt: string | null }>
+    >(PatQueries.mine, {}, actor);
     expect(rows[0]?.expiresAt).not.toBeNull();
     const expiresAt = Temporal.Instant.from(rows[0]?.expiresAt as string);
     const expected = Temporal.Now.instant().add({ hours: 24 * PAT_DEFAULT_EXPIRES_IN_DAYS });
@@ -361,7 +378,11 @@ describe("PAT create: MFA re-auth gate", () => {
       actor,
     );
     expect(err.details).toMatchObject({ reason: PatErrors.reauthRequired });
-    const rows = await mfaStack.http.queryOk<Array<{ id: string }>>(PatQueries.mine, {}, actor);
+    const { rows } = await mfaStack.http.queryOk<PatRowsEnvelope<{ id: string }>>(
+      PatQueries.mine,
+      {},
+      actor,
+    );
     expect(rows).toHaveLength(0);
   });
 
@@ -374,7 +395,11 @@ describe("PAT create: MFA re-auth gate", () => {
       actor,
     );
     expect(err.details).toMatchObject({ reason: PatErrors.reauthRequired });
-    const rows = await mfaStack.http.queryOk<Array<{ id: string }>>(PatQueries.mine, {}, actor);
+    const { rows } = await mfaStack.http.queryOk<PatRowsEnvelope<{ id: string }>>(
+      PatQueries.mine,
+      {},
+      actor,
+    );
     expect(rows).toHaveLength(0);
   });
 });
@@ -420,3 +445,108 @@ describe("PAT revoke on password change (#security)", () => {
     expect(res.status).toBe(200);
   });
 });
+
+describe("PAT list projection (fw#2548 Teil B)", () => {
+  test("the minted plaintext token is returned exactly once and never by query:mine", async () => {
+    const actor = await actorFor("secret-once@example.com");
+    const token = await mintToken(actor);
+
+    const first = await stack.http.queryOk<PatRowsEnvelope<{ prefix: string }>>(
+      PatQueries.mine,
+      {},
+      actor,
+    );
+    expect(JSON.stringify(first)).not.toContain(token);
+    expect(first.rows[0]?.prefix).toBeDefined();
+
+    // A second read confirms this isn't a one-request fluke — the plaintext
+    // never lands in the projection at all, so a later read can't leak it
+    // either.
+    const second = await stack.http.queryOk<PatRowsEnvelope<{ prefix: string }>>(
+      PatQueries.mine,
+      {},
+      actor,
+    );
+    expect(JSON.stringify(second)).not.toContain(token);
+  });
+
+  test("another user's tokens never appear in query:mine", async () => {
+    const actorA = await actorFor("owner-a@example.com");
+    const actorB = await actorFor("owner-b@example.com");
+    await mintToken(actorA);
+    await mintToken(actorB);
+
+    const { rows: rowsA } = await stack.http.queryOk<PatRowsEnvelope<{ id: string }>>(
+      PatQueries.mine,
+      {},
+      actorA,
+    );
+    const { rows: rowsB } = await stack.http.queryOk<PatRowsEnvelope<{ id: string }>>(
+      PatQueries.mine,
+      {},
+      actorB,
+    );
+    expect(rowsA).toHaveLength(1);
+    expect(rowsB).toHaveLength(1);
+    expect(rowsA[0]?.id).not.toBe(rowsB[0]?.id);
+  });
+
+  test("revoke of another user's token fails and leaves it usable", async () => {
+    const actorA = await actorFor("revoke-owner-a@example.com");
+    const actorB = await actorFor("revoke-owner-b@example.com");
+    const tokenA = await mintToken(actorA);
+    const { rows } = await stack.http.queryOk<PatRowsEnvelope<{ id: string }>>(
+      PatQueries.mine,
+      {},
+      actorA,
+    );
+    const tokenAId = rows[0]?.id;
+    expect(tokenAId).toBeDefined();
+
+    const err = await stack.http.writeErr(PatHandlers.revoke, { id: tokenAId }, actorB);
+    expect(err.details).toMatchObject({ reason: PatErrors.ownershipDenied });
+
+    const res = await h.authedPost("/api/query", tokenA, { type: PatQueries.mine, payload: {} });
+    expect(res.status).toBe(200);
+  });
+
+  test("status column reflects revoked/expired/active", async () => {
+    const actor = await actorFor("status-column@example.com");
+    await mintToken(actor);
+    const active = await stack.http.queryOk<PatRowsEnvelope<{ id: string; status: string }>>(
+      PatQueries.mine,
+      {},
+      actor,
+    );
+    expect(active.rows[0]?.status).toBe("active");
+
+    await stack.http.writeOk(PatHandlers.revoke, { id: active.rows[0]?.id }, actor);
+    const revoked = await stack.http.queryOk<PatRowsEnvelope<{ id: string; status: string }>>(
+      PatQueries.mine,
+      {},
+      actor,
+    );
+    expect(revoked.rows[0]?.status).toBe("revoked");
+
+    const expiredActor = await actorFor("status-column-expired@example.com");
+    await mintToken(expiredActor);
+    const beforeExpiry = await stack.http.queryOk<PatRowsEnvelope<{ id: string }>>(
+      PatQueries.mine,
+      {},
+      expiredActor,
+    );
+    const past = Temporal.Now.instant().subtract({ hours: 1 });
+    await updateMany(
+      stack.db,
+      apiTokenTable,
+      { expiresAt: past },
+      { id: beforeExpiry.rows[0]?.id },
+    );
+    const expired = await stack.http.queryOk<PatRowsEnvelope<{ id: string; status: string }>>(
+      PatQueries.mine,
+      {},
+      expiredActor,
+    );
+    expect(expired.rows[0]?.status).toBe("expired");
+  });
+});

package/src/personal-access-tokens/constants.ts

@@ -16,10 +16,13 @@ export const PatErrors = {
 // lets callers who genuinely want a long-lived token pass it explicitly.
 export const PAT_DEFAULT_EXPIRES_IN_DAYS = 90;
 
-// Dormant custom-screen id (r.screen) — the app places it via r.nav. The client
-// maps it to the PatTokensScreen component.
+// Declarative projectionList screen id — the caller's own tokens, revoke as a
+// row action. The app places it via r.nav.
 export const PAT_SCREEN_ID = "api-tokens";
 
+// Declarative secretMint screen id — mints a new token, reveals it once.
+export const PAT_MINT_SCREEN_ID = "api-token-create";
+
 export const PatHandlers = {
   create: "personal-access-tokens:write:create",
   revoke: "personal-access-tokens:write:revoke",

package/src/personal-access-tokens/expiry.ts

@@ -0,0 +1,7 @@
+import { Temporal } from "temporal-polyfill";
+
+export function isExpiredAt(expiresAt: { epochMilliseconds: number } | null): boolean {
+  return (
+    expiresAt !== null && expiresAt.epochMilliseconds <= Temporal.Now.instant().epochMilliseconds
+  );
+}

package/src/personal-access-tokens/feature.ts

@@ -5,15 +5,16 @@ import {
 import { PAT_TOKEN_PREFIX } from "@cosmicdrift/kumiko-framework/api";
 import { deriveEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { PAT_DEFAULT_RATE_LIMIT, PAT_FEATURE, PAT_SCREEN_ID, type PatRateLimit } from "./constants";
+import { PAT_DEFAULT_RATE_LIMIT, PAT_FEATURE, type PatRateLimit } from "./constants";
 import { buildAvailableScopesQuery } from "./handlers/available-scopes.query";
 import { type CreatePatOptions, createPatCreateHandler } from "./handlers/create.write";
 import { listPatQuery } from "./handlers/list.query";
 import { revokePatWrite } from "./handlers/revoke.write";
-import { PAT_FEATURE_I18N } from "./i18n";
+import { PAT_FEATURE_I18N, patScopeOptionTranslations } from "./i18n";
 import { createPatResolver } from "./resolver";
 import { apiTokenEntity } from "./schema/api-token";
 import type { PatScopeConfig } from "./scopes";
+import { createPatMintScreen, patListScreen } from "./screens";
 
 // Password-change is the only field-level trigger — see the postSave hook
 // below. MFA-enable/disable is wired separately (auth-mfa's
@@ -145,21 +146,11 @@ export function createPersonalAccessTokensFeature(
       availableScopes: r.queryHandler(buildAvailableScopesQuery(scopes)),
     };
 
-    // Dormant custom-screen — the client maps PAT_SCREEN_ID to PatTokensScreen;
-    // the app places it via r.nav in its logged-in settings area. dormant:
-    // true skips createKumikoApp's missing-client-plugin boot diagnostic
-    // (#2025) for apps that don't nav this screen (#2034).
-    // kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312
-    r.screen({
-      id: PAT_SCREEN_ID,
-      type: "custom",
-      renderer: { react: { __component: "PatTokensScreen" } },
-      access: { openToAll: true },
-      dormant: true,
-      description:
-        "Self-service screen where a signed-in user reviews their personal access tokens, mints a new one by picking a permission level per scope domain and an expiry, and revokes tokens they no longer need.",
-    });
-    r.translations({ keys: PAT_FEATURE_I18N });
+    // Declarative screens — list-with-revoke + mint-with-reveal. The app
+    // places `patListScreen` via r.nav in its logged-in settings area.
+    r.screen(patListScreen);
+    r.screen(createPatMintScreen(scopes));
+    r.translations({ keys: { ...PAT_FEATURE_I18N, ...patScopeOptionTranslations(scopes) } });
 
     // rateLimit flows into feature.exports so run-prod-app builds the
     // limiter from the same declaration — single source of truth. `scopes`

package/src/personal-access-tokens/handlers/list.query.ts

@@ -1,52 +1,111 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { definePagedQueryHandler, MAX_LIST_LIMIT } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { decryptStoredPii } from "../../shared";
+import { isExpiredAt } from "../expiry";
 import { apiTokenTable } from "../schema/api-token";
 
+// `sort` arrives raw from the client's query string. selectMany's orderBy has
+// no column-existence check — an unrecognised field just gets snake_cased and
+// quoted as-is (bun-db/query.ts columnOf) — so this allowlist is what stops a
+// client sorting by tokenHash or any other non-exposed column.
+const SORTABLE_COLUMNS = ["id", "name", "createdAt", "expiresAt", "revokedAt"] as const;
+type SortableColumn = (typeof SORTABLE_COLUMNS)[number];
+
+function isSortableColumn(value: string): value is SortableColumn {
+  return (SORTABLE_COLUMNS as readonly string[]).includes(value);
+}
+
+type PatStatus = "active" | "revoked" | "expired";
+
+function tokenStatus(row: {
+  revokedAt: unknown;
+  expiresAt: { epochMilliseconds: number } | null;
+}): PatStatus {
+  if (row.revokedAt !== null) return "revoked";
+  if (isExpiredAt(row.expiresAt)) return "expired";
+  return "active";
+}
+
+function parseScopeNames(raw: string): string[] {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((s): s is string => typeof s === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
 // The caller's own tokens — metadata only, never the hash or plaintext.
 // Includes revoked/expired rows so the UI can show history; `prefix` is the
 // only fragment of the secret ever exposed.
-export const listPatQuery = defineQueryHandler({
+export const listPatQuery = definePagedQueryHandler({
   name: "mine",
-  schema: z.object({}),
+  schema: z.object({
+    limit: z.number().int().nonnegative().max(MAX_LIST_LIMIT).optional(),
+    sort: z.string().optional(),
+    sortDirection: z.enum(["asc", "desc"]).optional(),
+  }),
   access: { openToAll: true },
   description:
-    "Lists the calling user's personal access tokens with metadata only (name, key prefix, scopes, created/expiry/revoked timestamps, including revoked ones) and never the token secret.",
+    "Lists the calling user's personal access tokens with metadata only (name, key prefix, scopes, computed status, created/expiry/revoked timestamps, including revoked ones) and never the token secret.",
+  outputSchema: z.object({
+    rows: z.array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        prefix: z.string(),
+        scopes: z.array(z.string()),
+        status: z.enum(["active", "revoked", "expired"]),
+        createdAt: z.unknown(),
+        expiresAt: z.unknown(),
+        revokedAt: z.unknown(),
+      }),
+    ),
+    nextCursor: z.string().nullable(),
+  }),
   handler: async (query, ctx) => {
+    const requestedSort = query.payload.sort;
+    const sortColumn: SortableColumn =
+      requestedSort !== undefined && isSortableColumn(requestedSort) ? requestedSort : "createdAt";
     const rows = await selectMany<{
       id: string;
       name: string;
       prefix: string;
       scopes: string;
       createdAt: unknown;
-      expiresAt: unknown;
+      expiresAt: { epochMilliseconds: number } | null;
       revokedAt: unknown;
     }>(
       ctx.db,
       apiTokenTable,
       { userId: query.user.id },
-      { orderBy: { col: "createdAt", direction: "desc" } },
+      {
+        // `id` as a tie-breaker keeps row order (and, with `limit` set, row
+        // selection) deterministic across identical requests — sortColumn
+        // alone isn't unique (e.g. many NULL revokedAt, or equal timestamps).
+        orderBy:
+          sortColumn === "id"
+            ? { col: "id", direction: query.payload.sortDirection ?? "desc" }
+            : [
+                { col: sortColumn, direction: query.payload.sortDirection ?? "desc" },
+                { col: "id", direction: "asc" },
+              ],
+        ...(query.payload.limit !== undefined && { limit: query.payload.limit }),
+      },
     );
-    return Promise.all(
+    const decryptedRows = await Promise.all(
       rows.map(async (r) => ({
         id: r.id,
         name: await decryptStoredPii(r.name, "name", "pat:list"),
         prefix: r.prefix,
         scopes: parseScopeNames(r.scopes),
+        status: tokenStatus(r),
         createdAt: r.createdAt,
         expiresAt: r.expiresAt,
         revokedAt: r.revokedAt,
       })),
     );
+    return { rows: decryptedRows, nextCursor: null };
   },
 });
-
-function parseScopeNames(raw: string): string[] {
-  try {
-    const parsed: unknown = JSON.parse(raw);
-    return Array.isArray(parsed) ? parsed.filter((s): s is string => typeof s === "string") : [];
-  } catch {
-    return [];
-  }
-}

package/src/personal-access-tokens/i18n.ts

@@ -1,5 +1,59 @@
+import type { PatScopeConfig } from "./scopes";
+
 type LocalizedString = { readonly en: string };
 
 export const PAT_FEATURE_I18N: Readonly<Record<string, LocalizedString>> = {
   "screen:api-tokens.title": { en: "Personal Access Tokens" },
+  "screen:api-token-create.title": { en: "Create a new token" },
+
+  "pat.list.col.name": { en: "Name" },
+  "pat.list.col.prefix": { en: "Token" },
+  "pat.list.col.scopes": { en: "Scopes" },
+  "pat.list.col.status": { en: "Status" },
+  "pat.list.col.created": { en: "Created" },
+  "pat.list.col.expires": { en: "Expires" },
+  "pat.list.revoke": { en: "Revoke" },
+  "pat.list.revoke.confirm": { en: "Revoke this token? Anything using it will stop working." },
+
+  "pat.create.title": { en: "Create a new token" },
+  "pat.create.submit": { en: "Create token" },
+  "pat.create.reauth": { en: "Confirm your identity" },
+
+  "pat.created.title": { en: "Token created" },
+  "pat.created.token": { en: "Your new token" },
+  "pat.created.hint": { en: "Copy this token now — for security it is shown only this once." },
+  "pat.created.dismiss": { en: "Done" },
+
+  // Field labels for the secretMint's synthesized pseudo-entity
+  // (`__action-form__`, see action-form-shim.ts) — required by the i18n
+  // boot-validator (requiredKeysFromScreen); the declarative renderer
+  // resolves these through the schema payload, not a client component's t().
+  "personal-access-tokens:entity:__action-form__:field:name": { en: "Name" },
+  "personal-access-tokens:entity:__action-form__:field:scopes": { en: "Per-API access" },
+  "personal-access-tokens:entity:__action-form__:field:expiresInDays": { en: "Expires in (days)" },
+  "personal-access-tokens:entity:__action-form__:field:currentPassword": {
+    en: "Password (to confirm)",
+  },
+  "personal-access-tokens:entity:__action-form__:field:mfaCode": { en: "2FA code (if enabled)" },
 };
+
+// Per-grant-option labels for the mint form's `scopes` multiSelect —
+// "<domain> (read)" / "<domain> (read & write)", matching the wording the
+// former custom screen showed. `def.label` is an app-authored raw display
+// string (not itself an i18n key).
+export function patScopeOptionTranslations(
+  scopes: PatScopeConfig,
+): Readonly<Record<string, LocalizedString>> {
+  const out: Record<string, LocalizedString> = {};
+  for (const [domain, def] of Object.entries(scopes)) {
+    out[`personal-access-tokens:entity:__action-form__:field:scopes:option:${domain}:read`] = {
+      en: `${def.label} (read)`,
+    };
+    if (def.write && def.write.length > 0) {
+      out[`personal-access-tokens:entity:__action-form__:field:scopes:option:${domain}:write`] = {
+        en: `${def.label} (read & write)`,
+      };
+    }
+  }
+  return out;
+}

package/src/personal-access-tokens/resolver.ts

@@ -2,7 +2,7 @@ import type { TokenVerifier } from "@cosmicdrift/kumiko-framework/api";
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import { Temporal } from "temporal-polyfill";
+import { isExpiredAt } from "./expiry";
 import { hashPatToken } from "./hash";
 import { resolvePatRoles } from "./roles";
 import { apiTokenTable } from "./schema/api-token";
@@ -29,12 +29,7 @@ export function createPatResolver(opts: {
     }>(db, apiTokenTable, { tokenHash: hashPatToken(rawToken) });
     if (!row) return null;
     if (row.revokedAt !== null) return null;
-    if (
-      row.expiresAt &&
-      row.expiresAt.epochMilliseconds <= Temporal.Now.instant().epochMilliseconds
-    ) {
-      return null;
-    }
+    if (isExpiredAt(row.expiresAt)) return null;
     const roles = await resolvePatRoles(db, row.userId, row.tenantId);
     if (!roles) return null;
     const granted = parseScopeNames(row.scopes);

package/src/personal-access-tokens/screens.ts

@@ -0,0 +1,107 @@
+import {
+  i18nKey,
+  type ProjectionListScreenDefinition,
+  type SecretMintScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { PAT_MINT_SCREEN_ID, PAT_SCREEN_ID, PatHandlers, PatQueries } from "./constants";
+import type { PatScopeConfig } from "./scopes";
+
+export const patListScreen: ProjectionListScreenDefinition = {
+  id: PAT_SCREEN_ID,
+  type: "projectionList",
+  query: PatQueries.mine,
+  defaultSort: { field: "createdAt", dir: "desc" },
+  columns: [
+    { field: "name", label: i18nKey("pat.list.col.name") },
+    { field: "prefix", label: i18nKey("pat.list.col.prefix") },
+    { field: "scopes", label: i18nKey("pat.list.col.scopes") },
+    { field: "status", label: i18nKey("pat.list.col.status") },
+    {
+      field: "createdAt",
+      label: i18nKey("pat.list.col.created"),
+      renderer: { format: "timestamp" },
+    },
+    {
+      field: "expiresAt",
+      label: i18nKey("pat.list.col.expires"),
+      renderer: { format: "timestamp" },
+    },
+  ],
+  rowActions: [
+    {
+      kind: "writeHandler",
+      id: "revoke",
+      label: i18nKey("pat.list.revoke"),
+      handler: PatHandlers.revoke,
+      style: "danger",
+      confirm: i18nKey("pat.list.revoke.confirm"),
+      visible: { field: "status", ne: "revoked" },
+    },
+  ],
+  toolbarActions: [
+    {
+      kind: "navigate",
+      id: "create",
+      label: i18nKey("pat.create.title"),
+      screen: PAT_MINT_SCREEN_ID,
+      style: "primary",
+    },
+  ],
+  access: { openToAll: true },
+};
+
+// Grant-string vocabulary for a scope config's multiSelect field — a
+// read-only domain offers only "<domain>:read", one with a non-empty
+// `write` set additionally offers "<domain>:write" (matches expandScopes/
+// parseGrant in scopes.ts).
+export function patGrantOptions(scopes: PatScopeConfig): string[] {
+  const out: string[] = [];
+  for (const [domain, def] of Object.entries(scopes)) {
+    out.push(`${domain}:read`);
+    if (def.write && def.write.length > 0) out.push(`${domain}:write`);
+  }
+  return out;
+}
+
+export function createPatMintScreen(scopes: PatScopeConfig): SecretMintScreenDefinition {
+  return {
+    id: PAT_MINT_SCREEN_ID,
+    type: "secretMint",
+    handler: PatHandlers.create,
+    fields: {
+      name: { type: "text", required: true, maxLength: 120 },
+      scopes: {
+        type: "multiSelect",
+        required: true,
+        display: "checkboxes",
+        options: patGrantOptions(scopes),
+      },
+      expiresInDays: { type: "number", integer: true, min: 1, max: 3650, default: 90 },
+      currentPassword: { type: "text", required: true, format: "password", sensitive: true },
+      mfaCode: { type: "text" },
+    },
+    layout: {
+      sections: [
+        { fields: ["name", "scopes", "expiresInDays"] },
+        // Separate section: create.write requires password (+ MFA code, if
+        // enrolled) even though the request is already session-authed.
+        {
+          title: i18nKey("pat.create.reauth"),
+          fields: ["currentPassword", "mfaCode"],
+        },
+      ],
+    },
+    submitLabel: i18nKey("pat.create.submit"),
+    reveal: {
+      title: i18nKey("pat.created.title"),
+      warning: i18nKey("pat.created.hint"),
+      confirmLabel: i18nKey("pat.created.dismiss"),
+      fields: [
+        { field: "token", label: i18nKey("pat.created.token"), display: "code", copyable: true },
+      ],
+    },
+    redirect: PAT_SCREEN_ID,
+    cancelTarget: PAT_SCREEN_ID,
+    access: { openToAll: true },
+  };
+}

package/src/shared/index.ts

@@ -17,7 +17,7 @@ export { isWithinGracePeriod } from "./grace-period";
 export { hasWhereRule } from "./has-where-rule";
 export { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash";
 export { mapWithConcurrency } from "./map-with-concurrency";
-export { parentRowIsVisible } from "./parent-visibility";
+export { joinRowParentIsVisible, parentRowIsVisible } from "./parent-visibility";
 export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing";
 export { sessionField } from "./session-field";
 export { sessionLocaleField } from "./session-locale-field";

package/src/shared/parent-visibility.ts

@@ -33,6 +33,10 @@ export async function parentRowIsVisible(
   const entity = registry.getEntity(entityType);
   if (!entity) return false;
 
+  // Mirrors the SQL gate, which drops join-row candidates for the same reason:
+  // resolving a host that is itself a join row would need recursive gating.
+  if (entity.parentRef !== undefined) return false;
+
   // A malformed id would abort the write transaction on a Postgres cast
   // error (22P02) instead of cleanly denying — reject it before it reaches
   // the executor.
@@ -46,3 +50,29 @@ export async function parentRowIsVisible(
 
   return (await executor.detail({ id: entityId }, user, db)) !== null;
 }
+
+// Write-path half of the parentRef gate (fw#2766). Resolves the join entity's
+// own `parentRef` declaration from the registry — the same object the read
+// path's SQL gate reads — so the field names and the allowedTypes allowlist
+// exist in exactly one place instead of once per path.
+export async function joinRowParentIsVisible(
+  registry: Registry,
+  joinEntityName: string,
+  payload: Readonly<Record<string, unknown>>,
+  user: SessionUser,
+  db: TenantDb,
+): Promise<boolean> {
+  const parentRef = registry.getEntity(joinEntityName)?.parentRef;
+  // A mount whose join entity lost its declaration can't derive a gate —
+  // deny rather than silently fall back to the pre-#2766 open behaviour.
+  if (parentRef === undefined) return false;
+
+  const entityType = payload[parentRef.entityTypeField];
+  const entityId = payload[parentRef.entityIdField];
+  if (typeof entityType !== "string" || typeof entityId !== "string") return false;
+  if (parentRef.allowedTypes !== undefined && !parentRef.allowedTypes.includes(entityType)) {
+    return false;
+  }
+
+  return parentRowIsVisible(registry, entityType, entityId, user, db);
+}