@simple-auth-kit/cli 1.0.0

package/registry/combos/express-prisma/test/harness.ts

@@ -0,0 +1,187 @@
+// Shared scaffolding for prove-cycle.ts, plus the contract each variant's
+// `variant-hooks.ts` implements. Everything here is variant-agnostic: it talks to the running
+// app over HTTP only, so it compiles against either variant's generated Prisma client.
+
+// Distinct from the nestjs-prisma reference combo's 4010 so both proofs can run at the same time.
+export const BASE_PORT = 4020;
+
+export interface CallOptions {
+  token?: string;
+  body?: unknown;
+  /** Sent as `X-Workspace-Id`. Ignored by variants that have no workspaces. */
+  workspaceId?: string;
+  /**
+   * Raw headers, merged last. The escape hatch for asserting what happens on malformed input —
+   * `workspaceId` above cannot express "sent, but empty", which is exactly a case worth proving.
+   */
+  headers?: Record<string, string>;
+}
+
+export interface AuthTokens {
+  accessToken: string;
+  refreshToken: string;
+  sessionId: string;
+}
+
+/** Everything a variant hook is allowed to use. Kept small on purpose — hooks drive the app, they do not reach around it. */
+export interface ProofContext {
+  call(method: string, path: string, opts?: CallOptions): Promise<{ status: number; body: any }>;
+  assert(condition: boolean, message: string): void;
+  signup(email: string, password: string): Promise<AuthTokens>;
+  uniqueEmail(prefix: string): string;
+}
+
+/** The freshly-signed-up user a variant is asked to promote. */
+export interface Principal {
+  userId: string;
+  email: string;
+  password: string;
+  tokens: AuthTokens;
+}
+
+/** How admin-scoped requests are made in this variant: which token, and what scope (if any) they name. */
+export interface AdminSession {
+  token: string;
+  /** Set only where admin authority is scoped to something narrower than the deployment. */
+  workspaceId?: string;
+  /**
+   * A freshly minted admin token. The proof's own admin token is created once and reused across
+   * a run that makes hundreds of calls, and `test/bootstrap.ts` deliberately runs a 2-second
+   * access-token TTL — so any section that makes several admin calls must re-mint rather than
+   * carry a token that may expire mid-section. That was a real 1-in-10 flake, not a hypothetical.
+   */
+  freshToken(): Promise<string>;
+}
+
+/**
+ * The three things that genuinely differ between variants when proving the same auth cycle.
+ * A variant supplies them from `variants/<variant>/test/variant-hooks.ts`.
+ */
+export interface VariantHooks {
+  variant: string;
+  /** Give the just-signed-up user administrative authority, and return how to make admin calls as them. */
+  makeAdmin(ctx: ProofContext, principal: Principal): Promise<AdminSession>;
+  /** Bring a user into the admin session's scope, so admin endpoints can act on them. No-op where the scope is the whole deployment. */
+  admitUser(ctx: ProofContext, admin: AdminSession, user: { userId: string; email: string }): Promise<void>;
+  /** Assertions that only make sense for this variant. Runs last, after the shared cycle has passed. */
+  proveVariantProperties(ctx: ProofContext, admin: AdminSession): Promise<void>;
+}
+
+/** One admin route, and the single permission slug that is supposed to open it. */
+export interface RouteProbe {
+  permission: string;
+  /** How the route reads in the mapping table, for assertion messages. */
+  label: string;
+  method: string;
+  path: string;
+  body?: unknown;
+}
+
+/**
+ * Every route under `/auth/admin`, paired with its `@CheckAbility` slug. Both variants expose
+ * exactly this surface — the workspace variant adds `/workspaces/*` routes on top, which its own
+ * hooks cover, so this list stays variant-agnostic.
+ *
+ * The order is load-bearing where a pair of routes undoes itself: assign before revoke, block
+ * before unblock. A caller can therefore run the whole list against one target user repeatedly
+ * and leave it exactly as it found it, which is what lets the proof run it once per permission.
+ */
+export function adminRouteProbes(args: { targetUserId: string; roleId: string; roleSlug: string; newRoleSlug: string; newPermissionSlug: string }): RouteProbe[] {
+  const { targetUserId, roleId, roleSlug, newRoleSlug, newPermissionSlug } = args;
+  const granted = encodeURIComponent("probe:granted");
+  return [
+    { permission: "users:read", label: "GET /auth/admin/users", method: "GET", path: "/auth/admin/users" },
+    { permission: "users:read", label: "GET /auth/admin/users/:userId", method: "GET", path: `/auth/admin/users/${targetUserId}` },
+    {
+      permission: "users:manage",
+      label: "PATCH /auth/admin/users/:userId",
+      method: "PATCH",
+      path: `/auth/admin/users/${targetUserId}`,
+      body: { displayName: "Probe User" },
+    },
+    { permission: "audit-log:read", label: "GET /auth/admin/audit-log", method: "GET", path: "/auth/admin/audit-log" },
+    { permission: "permissions:read", label: "GET /auth/admin/permissions", method: "GET", path: "/auth/admin/permissions" },
+    {
+      permission: "permissions:define",
+      label: "POST /auth/admin/permissions",
+      method: "POST",
+      path: "/auth/admin/permissions",
+      body: { slug: newPermissionSlug, displayName: "Probe permission", group: "Probe" },
+    },
+    { permission: "roles:manage", label: "GET /auth/admin/roles", method: "GET", path: "/auth/admin/roles" },
+    { permission: "roles:manage", label: "POST /auth/admin/roles", method: "POST", path: "/auth/admin/roles", body: { slug: newRoleSlug } },
+    {
+      permission: "roles:manage",
+      label: "POST /auth/admin/roles/:roleId/permissions",
+      method: "POST",
+      path: `/auth/admin/roles/${roleId}/permissions`,
+      body: { permission: "probe:attached" },
+    },
+    {
+      permission: "roles:manage",
+      label: "PATCH /auth/admin/roles/:roleId",
+      method: "PATCH",
+      path: `/auth/admin/roles/${roleId}`,
+      body: { displayName: "Probe Role" },
+    },
+    {
+      permission: "roles:assign",
+      label: "POST /auth/admin/users/:userId/roles",
+      method: "POST",
+      path: `/auth/admin/users/${targetUserId}/roles`,
+      body: { role: roleSlug },
+    },
+    {
+      permission: "roles:assign",
+      label: "POST /auth/admin/users/:userId/roles/:roleSlug/revoke",
+      method: "POST",
+      path: `/auth/admin/users/${targetUserId}/roles/${encodeURIComponent(roleSlug)}/revoke`,
+    },
+    {
+      permission: "permissions:grant",
+      label: "POST /auth/admin/users/:userId/permissions",
+      method: "POST",
+      path: `/auth/admin/users/${targetUserId}/permissions`,
+      body: { permission: "probe:granted" },
+    },
+    {
+      permission: "permissions:grant",
+      label: "POST /auth/admin/users/:userId/permissions/:permissionSlug/revoke",
+      method: "POST",
+      path: `/auth/admin/users/${targetUserId}/permissions/${granted}/revoke`,
+    },
+    { permission: "users:block", label: "POST /auth/admin/users/:userId/block", method: "POST", path: `/auth/admin/users/${targetUserId}/block` },
+    { permission: "users:block", label: "POST /auth/admin/users/:userId/unblock", method: "POST", path: `/auth/admin/users/${targetUserId}/unblock` },
+  ];
+}
+
+/** Reads a JWT's payload without verifying it — the proof only inspects which claims are present. */
+export function decodeJwtPayload(token: string): Record<string, unknown> {
+  return JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString("utf8"));
+}
+
+/**
+ * A token accessor that re-mints only when the one it holds is about to expire.
+ *
+ * The proof's admin makes hundreds of calls, and reusing one token across all of them is what
+ * produced a real 1-in-10 flake: with a 2-second access-token TTL the token could expire
+ * mid-section, and the resulting 401 surfaced as a confusing failure of a later assertion. The
+ * naive fix — log in before every admin call — is worse: core rate-limits login to 5 per minute
+ * per email, so the run would 429 itself.
+ *
+ * So: hold the token, check its `exp`, and log in again only inside the last `SKEW_SECONDS`. No
+ * call ever runs on a token that is about to die, and the login count stays at one per admin.
+ */
+const SKEW_SECONDS = 30;
+
+export function renewingToken(login: () => Promise<string>): () => Promise<string> {
+  let token: string | undefined;
+  return async () => {
+    if (token) {
+      const exp = decodeJwtPayload(token).exp as number;
+      if (exp * 1000 - Date.now() > SKEW_SECONDS * 1000) return token;
+    }
+    token = await login();
+    return token;
+  };
+}