@baseworks/iam 0.2.0

package/dist/chunk-26XPWBFV.js

@@ -0,0 +1,53 @@
+// src/events.ts
+import { z } from "zod";
+import { defineAggregate } from "@baseworks/foldbase";
+var UserEvents = defineAggregate("user", {
+  // First sight of an OIDC identity (auth-service POST /sync). id = new user id.
+  UserSynced: z.object({
+    subject: z.string().min(1),
+    issuer: z.string().min(1),
+    email: z.string().min(1),
+    name: z.string().nullable(),
+    picture: z.string().nullable(),
+    at: z.number().int()
+  }),
+  // A later /sync for the same identity refreshes the profile fields.
+  UserUpdated: z.object({
+    email: z.string().min(1),
+    name: z.string().nullable(),
+    picture: z.string().nullable(),
+    at: z.number().int()
+  })
+});
+var TOKEN_TYPES = ["user", "service", "cli", "agent"];
+var TokenType = z.enum(TOKEN_TYPES);
+var ApiTokenEvents = defineAggregate("api_token", {
+  TokenIssued: z.object({
+    tokenType: TokenType,
+    // Opaque context — iam does NOT validate org membership (org owns that).
+    organizationId: z.string().nullable(),
+    userId: z.string().nullable(),
+    name: z.string().min(1),
+    tokenHash: z.string().min(1),
+    keyPrefix: z.string().min(1),
+    scopes: z.string(),
+    // JSON string[]
+    metadata: z.string(),
+    // JSON object
+    expiresAt: z.number().int().nullable(),
+    at: z.number().int()
+  }),
+  // Throttled last-used stamp (not written on every request).
+  TokenUsed: z.object({
+    at: z.number().int()
+  }),
+  // Revoke removes the read-model row; the event stays in the log.
+  TokenRevoked: z.object({})
+});
+
+export {
+  UserEvents,
+  TOKEN_TYPES,
+  TokenType,
+  ApiTokenEvents
+};

package/dist/cli.d.ts

@@ -0,0 +1,21 @@
+import { Command } from 'commander';
+import { ApiClient } from '@baseworks/cli/client';
+
+/**
+ * Importable `iam` command group — identity + credentials only. Any app's CLI
+ * registers it:
+ *
+ *   import { buildIamCommand } from '@baseworks/iam/cli'
+ *   program.addCommand(buildIamCommand({ http, cliName: 'flect' }))
+ *
+ * `http` is a `@baseworks/cli` ApiClient whose base points at the app's IAM
+ * mount and carries the caller's bearer token. Org/role/member/PDP commands are
+ * NOT here — they live in `@baseworks/org/cli` (a user has no org of their own).
+ */
+interface IamCliDeps {
+    http: ApiClient;
+    cliName?: string;
+}
+declare function buildIamCommand(deps: IamCliDeps): Command;
+
+export { type IamCliDeps, buildIamCommand };

package/dist/cli.js

@@ -0,0 +1,68 @@
+// src/cli.ts
+import { Command } from "commander";
+import { kv, table, success, fatal, printOutput } from "@baseworks/cli/display";
+var die = (e) => fatal(e instanceof Error ? e.message : String(e));
+var outputOpt = (c) => c.option("-o, --output <format>", "output format: table | json | yaml", "table");
+function buildIamCommand(deps) {
+  const { http } = deps;
+  const iam = new Command("iam").description("identity & credentials (IAM)");
+  outputOpt(iam.command("whoami")).description("show the signed-in user identity").action(async (opts) => {
+    const { user } = await http.get("/me").catch(die);
+    if (opts.output && opts.output !== "table") {
+      return printOutput(user, opts.output, () => {
+      });
+    }
+    kv([
+      ["user", `${user.name ?? user.email} <${user.email}>`],
+      ["id", user.id]
+    ]);
+  });
+  const users = iam.command("users").description("user directory");
+  users.command("find <email>").description("resolve a user id by exact email (for invites)").action(async (email) => {
+    const { user } = await http.get(
+      `/users/lookup?email=${encodeURIComponent(email)}`
+    ).catch(die);
+    kv([
+      ["id", user.id],
+      ["email", user.email],
+      ["name", user.name ?? "\u2014"]
+    ]);
+  });
+  const token = iam.command("token").description("api tokens (service / cli / agent credentials)");
+  outputOpt(token.command("list")).description("active tokens you can see").action(async (opts) => {
+    const { tokens } = await http.get(
+      "/v1/tokens"
+    ).catch(die);
+    printOutput(
+      tokens,
+      opts.output,
+      () => table(tokens, [
+        { key: "name", label: "NAME" },
+        { key: "type", label: "TYPE" },
+        { key: "keyPrefix", label: "PREFIX" },
+        { key: "id", label: "ID" }
+      ])
+    );
+  });
+  token.command("issue <name>").description("issue a token; the secret is printed once").option("--type <type>", "user | service | cli | agent", "service").option("--org <id>", "bind to an organization (opaque context)").option("--scope <scope...>", "grant scopes").action(async (name, opts) => {
+    const res = await http.post("/v1/tokens", {
+      name,
+      type: opts.type,
+      organizationId: opts.org ?? null,
+      scopes: opts.scope ?? []
+    }).catch(die);
+    success(`token issued: ${res.token.id}`);
+    kv([
+      ["secret", res.secret],
+      ["note", "store it now \u2014 it is not shown again"]
+    ]);
+  });
+  token.command("revoke <id>").description("revoke a token by id").action(async (id) => {
+    await http.del(`/v1/tokens/${encodeURIComponent(id)}`).catch(die);
+    success(`token revoked: ${id}`);
+  });
+  return iam;
+}
+export {
+  buildIamCommand
+};

package/dist/client.d.ts

@@ -0,0 +1,155 @@
+import { TokenType } from './events.js';
+export { TOKEN_TYPES } from './events.js';
+import '@baseworks/foldbase';
+import 'zod';
+
+interface UserRow {
+    id: string;
+    subject: string;
+    issuer: string;
+    email: string;
+    name: string | null;
+    picture: string | null;
+    created_at: number;
+    updated_at: number;
+}
+interface ApiTokenRow {
+    id: string;
+    token_type: TokenType;
+    organization_id: string | null;
+    user_id: string | null;
+    name: string;
+    token_hash: string;
+    key_prefix: string;
+    scopes: string;
+    metadata: string;
+    expires_at: number | null;
+    last_used_at: number | null;
+    created_at: number;
+    updated_at: number;
+}
+interface User {
+    id: string;
+    subject: string;
+    issuer: string;
+    email: string;
+    name: string | null;
+    picture: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Public-safe identity projection (returned by /me and /users/lookup). */
+interface PublicUser {
+    id: string;
+    email: string;
+    name: string | null;
+}
+/** An OIDC identity presented to POST /sync (before a user id exists). */
+interface OidcIdentity {
+    subject: string;
+    issuer: string;
+    email: string;
+    name?: string | null;
+    picture?: string | null;
+}
+/** A token as listed — never carries the secret or its hash. */
+interface ApiToken {
+    id: string;
+    type: TokenType;
+    organizationId: string | null;
+    userId: string | null;
+    name: string;
+    keyPrefix: string;
+    scopes: string[];
+    metadata: Record<string, unknown>;
+    expiresAt: number | null;
+    lastUsedAt: number | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/** The one-time issue response — `token` is the secret, shown only here. */
+interface IssuedToken {
+    token: ApiToken;
+    /** The full secret; surfaced exactly once at creation. */
+    secret: string;
+}
+/** The identity a verified token resolves to. */
+interface TokenPrincipal {
+    tokenId: string;
+    type: TokenType;
+    organizationId: string | null;
+    userId: string | null;
+    scopes: string[];
+}
+
+/** Forwarded end-user identity (X-Auth-*) for a trusted service caller. */
+interface AuthContext {
+    uid?: string;
+    role?: string;
+    email?: string;
+}
+interface IamClientOptions {
+    /** Base URL of iam-service (resolved by the SDK, e.g. IAM_SERVICE_URL). */
+    baseUrl: string;
+    /** Bearer token — the caller's service or user token. */
+    token?: string;
+    /** Forwarded end-user identity. */
+    auth?: AuthContext;
+    /** Injectable fetch (tests / non-global environments). */
+    fetch?: typeof fetch;
+}
+/** Thrown on any non-2xx response from iam-service. */
+declare class IamError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message?: string);
+}
+/** Minimal ApiClient shape — structurally compatible with @baseworks/cli. */
+interface HttpClient {
+    api<T>(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    get<T>(path: string, headers?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body: unknown, headers?: Record<string, string>): Promise<T>;
+    del<T>(path: string, headers?: Record<string, string>): Promise<T>;
+}
+/**
+ * Typed HTTP client for iam-service. Zod-free at the boundary (the service
+ * validates); a thin, ergonomic wrapper over the REST surface. `.http` exposes
+ * a generic ApiClient the CLI plugin consumes.
+ */
+declare class IamClient {
+    private readonly opts;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(opts: IamClientOptions);
+    /** Return a new client that forwards a different end-user identity. */
+    withAuth(auth: AuthContext): IamClient;
+    private headers;
+    api<T>(method: string, path: string, body?: unknown, extra?: Record<string, string>): Promise<T>;
+    /** Generic ApiClient (get/post/del) — used by the CLI plugin. */
+    get http(): HttpClient;
+    /** The signed-in user's own identity (no orgs — those live in @baseworks/org). */
+    me(): Promise<PublicUser>;
+    /** Upsert an OIDC identity → the platform user. Called by auth-service (no auth). */
+    sync(identity: OidcIdentity): Promise<{
+        id: string;
+    }>;
+    /** Resolve a user id by exact email (invite flows). */
+    lookupByEmail(email: string): Promise<PublicUser>;
+    issueToken(input: {
+        name: string;
+        type?: TokenType;
+        organizationId?: string | null;
+        userId?: string | null;
+        scopes?: string[];
+        expiresAt?: number | null;
+        metadata?: Record<string, unknown>;
+    }): Promise<IssuedToken>;
+    listTokens(): Promise<ApiToken[]>;
+    revokeToken(id: string): Promise<void>;
+    /** Verify a raw token secret → its principal, or throw IamError(401). */
+    verifyToken(secret: string): Promise<TokenPrincipal>;
+}
+/** Factory used by the SDK capability registry. */
+declare function createIamClient(opts: IamClientOptions): IamClient;
+
+export { type ApiToken, type ApiTokenRow, type AuthContext, type HttpClient, IamClient, type IamClientOptions, IamError, type IssuedToken, type OidcIdentity, type PublicUser, type TokenPrincipal, TokenType, type User, type UserRow, createIamClient };

package/dist/client.js

@@ -0,0 +1,105 @@
+import {
+  TOKEN_TYPES
+} from "./chunk-26XPWBFV.js";
+
+// src/client.ts
+var IamError = class extends Error {
+  constructor(status, code, message) {
+    super(message ?? code);
+    this.status = status;
+    this.code = code;
+    this.name = "IamError";
+  }
+  status;
+  code;
+};
+var IamClient = class _IamClient {
+  constructor(opts) {
+    this.opts = opts;
+    this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+  }
+  opts;
+  baseUrl;
+  fetchImpl;
+  /** Return a new client that forwards a different end-user identity. */
+  withAuth(auth) {
+    return new _IamClient({ ...this.opts, auth });
+  }
+  headers(json, extra = {}) {
+    const h = {};
+    if (json) h["Content-Type"] = "application/json";
+    if (this.opts.token) h["Authorization"] = `Bearer ${this.opts.token}`;
+    if (this.opts.auth?.uid) h["X-Auth-UID"] = this.opts.auth.uid;
+    if (this.opts.auth?.role) h["X-Auth-Role"] = this.opts.auth.role;
+    if (this.opts.auth?.email) h["X-Auth-Email"] = this.opts.auth.email;
+    return { ...h, ...extra };
+  }
+  async api(method, path, body, extra = {}) {
+    const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method,
+      headers: this.headers(body !== void 0, extra),
+      ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+    });
+    if (res.status === 204) return null;
+    const text = await res.text();
+    const data = text ? JSON.parse(text) : void 0;
+    if (!res.ok) {
+      const e = data ?? {};
+      const code = typeof e.error === "string" ? e.error : e.error?.code ?? "error";
+      const msg = typeof e.error === "object" ? e.error?.message : e.message;
+      throw new IamError(res.status, code, msg);
+    }
+    return data;
+  }
+  /** Generic ApiClient (get/post/del) — used by the CLI plugin. */
+  get http() {
+    return {
+      api: this.api.bind(this),
+      get: (p, h) => this.api("GET", p, void 0, h),
+      post: (p, b, h) => this.api("POST", p, b, h),
+      del: (p, h) => this.api("DELETE", p, void 0, h)
+    };
+  }
+  // ── identity ────────────────────────────────────────────────────────────────
+  /** The signed-in user's own identity (no orgs — those live in @baseworks/org). */
+  async me() {
+    const { user } = await this.api("GET", "/me");
+    return user;
+  }
+  /** Upsert an OIDC identity → the platform user. Called by auth-service (no auth). */
+  async sync(identity) {
+    const { user } = await this.api("POST", "/sync", identity);
+    return user;
+  }
+  /** Resolve a user id by exact email (invite flows). */
+  async lookupByEmail(email) {
+    const { user } = await this.api("GET", `/users/lookup?email=${encodeURIComponent(email)}`);
+    return user;
+  }
+  // ── credentials (api tokens) ─────────────────────────────────────────────────
+  async issueToken(input) {
+    return this.api("POST", "/v1/tokens", input);
+  }
+  async listTokens() {
+    const { tokens } = await this.api("GET", "/v1/tokens");
+    return tokens;
+  }
+  async revokeToken(id) {
+    await this.api("DELETE", `/v1/tokens/${encodeURIComponent(id)}`);
+  }
+  /** Verify a raw token secret → its principal, or throw IamError(401). */
+  async verifyToken(secret) {
+    const { principal } = await this.api("POST", "/v1/tokens/verify", { token: secret });
+    return principal;
+  }
+};
+function createIamClient(opts) {
+  return new IamClient(opts);
+}
+export {
+  IamClient,
+  IamError,
+  TOKEN_TYPES,
+  createIamClient
+};

package/dist/events.d.ts

@@ -0,0 +1,111 @@
+import * as _baseworks_foldbase from '@baseworks/foldbase';
+import { z } from 'zod';
+
+/**
+ * Event catalogs — the single source of truth for iam-service payloads.
+ * Shared by the service (typed emit) and tests. Two aggregates:
+ *
+ *   user       — a platform identity, keyed on (issuer, subject); id = user id
+ *   api_token   — a service/cli/agent credential; id = token id
+ *
+ * IAM is identity + credentials ONLY. Roles, memberships, orgs and the PDP live
+ * in @baseworks/org — a user has no org of their own, only memberships, so every
+ * role question is an org question (see iam-service/AGENTS.md).
+ *
+ * All timestamps are epoch millis carried in the payload (`at`) so folds stay
+ * deterministic. `scopes`/`metadata` are JSON strings the service serializes
+ * before emit (mirrors org-service's `metadata` convention).
+ */
+declare const UserEvents: _baseworks_foldbase.EventCatalog<{
+    UserSynced: z.ZodObject<{
+        subject: z.ZodString;
+        issuer: z.ZodString;
+        email: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        picture: z.ZodNullable<z.ZodString>;
+        at: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        email: string;
+        at: number;
+        subject: string;
+        issuer: string;
+        name: string | null;
+        picture: string | null;
+    }, {
+        email: string;
+        at: number;
+        subject: string;
+        issuer: string;
+        name: string | null;
+        picture: string | null;
+    }>;
+    UserUpdated: z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        picture: z.ZodNullable<z.ZodString>;
+        at: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        email: string;
+        at: number;
+        name: string | null;
+        picture: string | null;
+    }, {
+        email: string;
+        at: number;
+        name: string | null;
+        picture: string | null;
+    }>;
+}> & {
+    newId(): string;
+};
+declare const TOKEN_TYPES: readonly ["user", "service", "cli", "agent"];
+declare const TokenType: z.ZodEnum<["user", "service", "cli", "agent"]>;
+type TokenType = z.infer<typeof TokenType>;
+declare const ApiTokenEvents: _baseworks_foldbase.EventCatalog<{
+    TokenIssued: z.ZodObject<{
+        tokenType: z.ZodEnum<["user", "service", "cli", "agent"]>;
+        organizationId: z.ZodNullable<z.ZodString>;
+        userId: z.ZodNullable<z.ZodString>;
+        name: z.ZodString;
+        tokenHash: z.ZodString;
+        keyPrefix: z.ZodString;
+        scopes: z.ZodString;
+        metadata: z.ZodString;
+        expiresAt: z.ZodNullable<z.ZodNumber>;
+        at: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        at: number;
+        name: string;
+        tokenType: "user" | "service" | "cli" | "agent";
+        organizationId: string | null;
+        userId: string | null;
+        tokenHash: string;
+        keyPrefix: string;
+        scopes: string;
+        metadata: string;
+        expiresAt: number | null;
+    }, {
+        at: number;
+        name: string;
+        tokenType: "user" | "service" | "cli" | "agent";
+        organizationId: string | null;
+        userId: string | null;
+        tokenHash: string;
+        keyPrefix: string;
+        scopes: string;
+        metadata: string;
+        expiresAt: number | null;
+    }>;
+    TokenUsed: z.ZodObject<{
+        at: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        at: number;
+    }, {
+        at: number;
+    }>;
+    TokenRevoked: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+}> & {
+    newId(): string;
+};
+
+export { ApiTokenEvents, TOKEN_TYPES, TokenType, UserEvents };

package/dist/events.js

@@ -0,0 +1,12 @@
+import {
+  ApiTokenEvents,
+  TOKEN_TYPES,
+  TokenType,
+  UserEvents
+} from "./chunk-26XPWBFV.js";
+export {
+  ApiTokenEvents,
+  TOKEN_TYPES,
+  TokenType,
+  UserEvents
+};

package/dist/projections.d.ts

@@ -0,0 +1,19 @@
+import * as _baseworks_foldbase from '@baseworks/foldbase';
+import { PolicyDef } from '@baseworks/foldbase';
+
+/**
+ * Read-model definitions the service registers on boot (idempotent, like
+ * migrations). Columns are inferred from the event field types. `updated_at` is
+ * part of foldbase's read-model spine (server-maintained) so it is never
+ * declared; the stream id is the `id` column.
+ *
+ * The service is the authorization layer (route handlers enforce end-user
+ * scoping), so policies are permissive for the service's own `admin` identity.
+ */
+declare const readUsers: _baseworks_foldbase.ProjectionSpec;
+declare const readApiTokens: _baseworks_foldbase.ProjectionSpec;
+declare const PROJECTIONS: readonly [_baseworks_foldbase.ProjectionSpec, _baseworks_foldbase.ProjectionSpec];
+/** Permissive policies for the service's own `admin` identity. */
+declare const POLICIES: PolicyDef[];
+
+export { POLICIES, PROJECTIONS, readApiTokens, readUsers };

package/dist/projections.js

@@ -0,0 +1,51 @@
+import {
+  ApiTokenEvents,
+  UserEvents
+} from "./chunk-26XPWBFV.js";
+
+// src/projections.ts
+import { defineProjection } from "@baseworks/foldbase";
+var readUsers = defineProjection("users", UserEvents, (on) => ({
+  UserSynced: on.UserSynced.upsert((e) => ({
+    subject: e.subject,
+    issuer: e.issuer,
+    email: e.email,
+    name: e.name,
+    picture: e.picture,
+    created_at: e.at
+  })),
+  UserUpdated: on.UserUpdated.upsert((e) => ({
+    email: e.email,
+    name: e.name,
+    picture: e.picture
+  }))
+}));
+var readApiTokens = defineProjection("api_tokens", ApiTokenEvents, (on) => ({
+  TokenIssued: on.TokenIssued.upsert((e) => ({
+    token_type: e.tokenType,
+    organization_id: e.organizationId,
+    user_id: e.userId,
+    name: e.name,
+    token_hash: e.tokenHash,
+    key_prefix: e.keyPrefix,
+    scopes: e.scopes,
+    metadata: e.metadata,
+    expires_at: e.expiresAt,
+    created_at: e.at
+  })),
+  TokenUsed: on.TokenUsed.upsert((e) => ({
+    last_used_at: e.at
+  })),
+  TokenRevoked: on.TokenRevoked.delete()
+}));
+var PROJECTIONS = [readUsers, readApiTokens];
+var POLICIES = [
+  { name: "users", role: "admin" },
+  { name: "api_tokens", role: "admin" }
+];
+export {
+  POLICIES,
+  PROJECTIONS,
+  readApiTokens,
+  readUsers
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@baseworks/iam",
+  "version": "0.2.0",
+  "description": "IAM capability: identity (users) + credentials (api tokens). Typed HTTP client, foldbase event catalog, projections, and CLI plugin for iam-service. Contract-first, versioned with the service. Roles/PDP live in @baseworks/org.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/client.js",
+    "./events": "./dist/events.js",
+    "./projections": "./dist/projections.js",
+    "./cli": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@baseworks/cli": "^0.2.0",
+    "commander": "^15.0.0",
+    "zod": "^3.25.76",
+    "@baseworks/foldbase": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "msw": "^2.14.6",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9",
+    "@baseworks/tsconfig": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/__tests__/cli.test.ts

@@ -0,0 +1,69 @@
+/// <reference types="vitest/globals" />
+import { beforeAll, afterEach, afterAll, describe, it, expect } from 'vitest'
+import { run, mocks, server } from './helpers.js'
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'warn' }))
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+
+const USER = { id: '019f05bd-ebf7-7db6-956d-f323dfadba50', email: 'ali@acme.test', name: 'Ali' }
+
+// ── whoami ────────────────────────────────────────────────────────────────────
+
+describe('flect iam whoami', () => {
+  it('shows the signed-in identity', async () => {
+    mocks.mockGet('/me', { user: USER })
+    const r = await run(['iam', 'whoami'])
+    expect(r.exitCode).toBe(0)
+    expect(r.stdout).toContain('ali@acme.test')
+    expect(r.stdout).toContain(USER.id)
+  })
+
+  it('-o json returns the raw user', async () => {
+    mocks.mockGet('/me', { user: USER })
+    const r = await run(['iam', 'whoami', '-o', 'json'])
+    expect(r.exitCode).toBe(0)
+    expect(JSON.parse(r.stdout)).toMatchObject({ email: 'ali@acme.test' })
+  })
+})
+
+// ── users find ────────────────────────────────────────────────────────────────
+
+describe('flect iam users find', () => {
+  it('resolves a user id by email', async () => {
+    mocks.mockGet('/users/lookup', { user: USER })
+    const r = await run(['iam', 'users', 'find', 'ali@acme.test'])
+    expect(r.exitCode).toBe(0)
+    expect(r.stdout).toContain(USER.id)
+    expect(r.stdout).toContain('ali@acme.test')
+  })
+})
+
+// ── token ─────────────────────────────────────────────────────────────────────
+
+describe('flect iam token', () => {
+  it('list renders NAME / TYPE / PREFIX columns', async () => {
+    mocks.mockGet('/v1/tokens', {
+      tokens: [{ id: 't1', name: 'ci', type: 'service', keyPrefix: 'bwt_abc12345', expiresAt: null }],
+    })
+    const r = await run(['iam', 'token', 'list'])
+    expect(r.exitCode).toBe(0)
+    expect(r.stdout).toContain('ci')
+    expect(r.stdout).toContain('service')
+    expect(r.stdout).toContain('bwt_abc12345')
+  })
+
+  it('issue prints the one-time secret', async () => {
+    mocks.mockPost('/v1/tokens', { token: { id: 't1', keyPrefix: 'bwt_secret1234' }, secret: 'bwt_secret1234_rest' })
+    const r = await run(['iam', 'token', 'issue', 'ci', '--type', 'service'])
+    expect(r.exitCode).toBe(0)
+    expect(r.stdout).toContain('bwt_secret1234_rest')
+  })
+
+  it('revoke calls DELETE and reports success', async () => {
+    mocks.mockDelete('/v1/tokens/t1')
+    const r = await run(['iam', 'token', 'revoke', 't1'])
+    expect(r.exitCode).toBe(0)
+    expect(r.stdout).toContain('t1')
+  })
+})

package/src/__tests__/helpers.ts

@@ -0,0 +1,24 @@
+import { Command } from 'commander'
+import { buildIamCommand } from '../cli.js'
+import { createApiClient } from '@baseworks/cli/client'
+import { runCommand, createMocks, server } from '@baseworks/cli/testing'
+
+export { runCommand, server }
+
+export const TEST_BASE = 'http://iam.test'
+
+export const mocks = createMocks(TEST_BASE)
+
+export function makeProgram(token = 'test-token') {
+  const http = createApiClient(
+    () => token,
+    () => TEST_BASE,
+  )
+  const program = new Command('flect').exitOverride().enablePositionalOptions()
+  program.addCommand(buildIamCommand({ http, cliName: 'flect' }))
+  return program
+}
+
+export function run(args: string[]) {
+  return runCommand(makeProgram(), args)
+}

package/src/cli.ts

@@ -0,0 +1,115 @@
+import { Command } from 'commander'
+import { kv, table, success, fatal, printOutput } from '@baseworks/cli/display'
+import type { ApiClient } from '@baseworks/cli/client'
+
+/**
+ * Importable `iam` command group — identity + credentials only. Any app's CLI
+ * registers it:
+ *
+ *   import { buildIamCommand } from '@baseworks/iam/cli'
+ *   program.addCommand(buildIamCommand({ http, cliName: 'flect' }))
+ *
+ * `http` is a `@baseworks/cli` ApiClient whose base points at the app's IAM
+ * mount and carries the caller's bearer token. Org/role/member/PDP commands are
+ * NOT here — they live in `@baseworks/org/cli` (a user has no org of their own).
+ */
+export interface IamCliDeps {
+  http: ApiClient
+  cliName?: string
+}
+
+const die = (e: unknown): never => fatal(e instanceof Error ? e.message : String(e))
+const outputOpt = (c: Command) => c.option('-o, --output <format>', 'output format: table | json | yaml', 'table')
+
+export function buildIamCommand(deps: IamCliDeps): Command {
+  const { http } = deps
+  const iam = new Command('iam').description('identity & credentials (IAM)')
+
+  // ── whoami ──────────────────────────────────────────────────────────────────
+  outputOpt(iam.command('whoami'))
+    .description('show the signed-in user identity')
+    .action(async (opts: { output?: string }) => {
+      const { user } = await http
+        .get<{ user: { id: string; email: string; name: string | null } }>('/me')
+        .catch(die)
+      if (opts.output && opts.output !== 'table') {
+        return printOutput(user as unknown as Record<string, unknown>, opts.output, () => {})
+      }
+      kv([
+        ['user', `${user.name ?? user.email} <${user.email}>`],
+        ['id', user.id],
+      ])
+    })
+
+  // ── users ─────────────────────────────────────────────────────────────────--
+  const users = iam.command('users').description('user directory')
+
+  users
+    .command('find <email>')
+    .description('resolve a user id by exact email (for invites)')
+    .action(async (email: string) => {
+      const { user } = await http
+        .get<{ user: { id: string; email: string; name: string | null } }>(
+          `/users/lookup?email=${encodeURIComponent(email)}`,
+        )
+        .catch(die)
+      kv([
+        ['id', user.id],
+        ['email', user.email],
+        ['name', user.name ?? '—'],
+      ])
+    })
+
+  // ── token (credentials) ───────────────────────────────────────────────────--
+  const token = iam.command('token').description('api tokens (service / cli / agent credentials)')
+
+  outputOpt(token.command('list'))
+    .description('active tokens you can see')
+    .action(async (opts: { output?: string }) => {
+      const { tokens } = await http
+        .get<{ tokens: Array<{ id: string; name: string; type: string; keyPrefix: string; expiresAt: number | null }> }>(
+          '/v1/tokens',
+        )
+        .catch(die)
+      printOutput(tokens as unknown as Record<string, unknown>[], opts.output, () =>
+        table(tokens as unknown as Record<string, unknown>[], [
+          { key: 'name', label: 'NAME' },
+          { key: 'type', label: 'TYPE' },
+          { key: 'keyPrefix', label: 'PREFIX' },
+          { key: 'id', label: 'ID' },
+        ]),
+      )
+    })
+
+  token
+    .command('issue <name>')
+    .description('issue a token; the secret is printed once')
+    .option('--type <type>', 'user | service | cli | agent', 'service')
+    .option('--org <id>', 'bind to an organization (opaque context)')
+    .option('--scope <scope...>', 'grant scopes')
+    .action(async (name: string, opts: { type?: string; org?: string; scope?: string[] }) => {
+      const res = await http
+        .post<{ token: { id: string; keyPrefix: string }; secret: string }>('/v1/tokens', {
+          name,
+          type: opts.type,
+          organizationId: opts.org ?? null,
+          scopes: opts.scope ?? [],
+        })
+        .catch(die)
+      success(`token issued: ${res.token.id}`)
+      kv([
+        ['secret', res.secret],
+        ['note', 'store it now — it is not shown again'],
+      ])
+    })
+
+  token
+    .command('revoke <id>')
+    .description('revoke a token by id')
+    .action(async (id: string) => {
+      await http.del(`/v1/tokens/${encodeURIComponent(id)}`).catch(die)
+      success(`token revoked: ${id}`)
+    })
+
+  return iam
+}

package/src/client.ts

@@ -0,0 +1,166 @@
+import type { PublicUser, OidcIdentity, ApiToken, IssuedToken, TokenPrincipal, TokenType } from './types.js'
+
+// Value re-export (a runtime const, not just a type) so consumers can build
+// validators from it, e.g. `z.enum(TOKEN_TYPES)`.
+export { TOKEN_TYPES } from './types.js'
+
+export type {
+  User,
+  PublicUser,
+  OidcIdentity,
+  ApiToken,
+  IssuedToken,
+  TokenPrincipal,
+  TokenType,
+  UserRow,
+  ApiTokenRow,
+} from './types.js'
+
+/** Forwarded end-user identity (X-Auth-*) for a trusted service caller. */
+export interface AuthContext {
+  uid?: string
+  role?: string
+  email?: string
+}
+
+export interface IamClientOptions {
+  /** Base URL of iam-service (resolved by the SDK, e.g. IAM_SERVICE_URL). */
+  baseUrl: string
+  /** Bearer token — the caller's service or user token. */
+  token?: string
+  /** Forwarded end-user identity. */
+  auth?: AuthContext
+  /** Injectable fetch (tests / non-global environments). */
+  fetch?: typeof fetch
+}
+
+/** Thrown on any non-2xx response from iam-service. */
+export class IamError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message?: string,
+  ) {
+    super(message ?? code)
+    this.name = 'IamError'
+  }
+}
+
+/** Minimal ApiClient shape — structurally compatible with @baseworks/cli. */
+export interface HttpClient {
+  api<T>(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<T>
+  get<T>(path: string, headers?: Record<string, string>): Promise<T>
+  post<T>(path: string, body: unknown, headers?: Record<string, string>): Promise<T>
+  del<T>(path: string, headers?: Record<string, string>): Promise<T>
+}
+
+/**
+ * Typed HTTP client for iam-service. Zod-free at the boundary (the service
+ * validates); a thin, ergonomic wrapper over the REST surface. `.http` exposes
+ * a generic ApiClient the CLI plugin consumes.
+ */
+export class IamClient {
+  private readonly baseUrl: string
+  private readonly fetchImpl: typeof fetch
+  constructor(private readonly opts: IamClientOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/$/, '')
+    this.fetchImpl = opts.fetch ?? globalThis.fetch
+  }
+
+  /** Return a new client that forwards a different end-user identity. */
+  withAuth(auth: AuthContext): IamClient {
+    return new IamClient({ ...this.opts, auth })
+  }
+
+  private headers(json: boolean, extra: Record<string, string> = {}): Record<string, string> {
+    const h: Record<string, string> = {}
+    if (json) h['Content-Type'] = 'application/json'
+    if (this.opts.token) h['Authorization'] = `Bearer ${this.opts.token}`
+    if (this.opts.auth?.uid) h['X-Auth-UID'] = this.opts.auth.uid
+    if (this.opts.auth?.role) h['X-Auth-Role'] = this.opts.auth.role
+    if (this.opts.auth?.email) h['X-Auth-Email'] = this.opts.auth.email
+    return { ...h, ...extra }
+  }
+
+  async api<T>(method: string, path: string, body?: unknown, extra: Record<string, string> = {}): Promise<T> {
+    const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method,
+      headers: this.headers(body !== undefined, extra),
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    })
+    if (res.status === 204) return null as T
+    const text = await res.text()
+    const data = text ? (JSON.parse(text) as unknown) : undefined
+    if (!res.ok) {
+      const e = (data ?? {}) as { error?: string | { code?: string; message?: string }; message?: string }
+      const code = typeof e.error === 'string' ? e.error : e.error?.code ?? 'error'
+      const msg = typeof e.error === 'object' ? e.error?.message : e.message
+      throw new IamError(res.status, code, msg)
+    }
+    return data as T
+  }
+
+  /** Generic ApiClient (get/post/del) — used by the CLI plugin. */
+  get http(): HttpClient {
+    return {
+      api: this.api.bind(this),
+      get: <T>(p: string, h?: Record<string, string>) => this.api<T>('GET', p, undefined, h),
+      post: <T>(p: string, b: unknown, h?: Record<string, string>) => this.api<T>('POST', p, b, h),
+      del: <T>(p: string, h?: Record<string, string>) => this.api<T>('DELETE', p, undefined, h),
+    }
+  }
+
+  // ── identity ────────────────────────────────────────────────────────────────
+
+  /** The signed-in user's own identity (no orgs — those live in @baseworks/org). */
+  async me(): Promise<PublicUser> {
+    const { user } = await this.api<{ user: PublicUser }>('GET', '/me')
+    return user
+  }
+
+  /** Upsert an OIDC identity → the platform user. Called by auth-service (no auth). */
+  async sync(identity: OidcIdentity): Promise<{ id: string }> {
+    const { user } = await this.api<{ user: { id: string } }>('POST', '/sync', identity)
+    return user
+  }
+
+  /** Resolve a user id by exact email (invite flows). */
+  async lookupByEmail(email: string): Promise<PublicUser> {
+    const { user } = await this.api<{ user: PublicUser }>('GET', `/users/lookup?email=${encodeURIComponent(email)}`)
+    return user
+  }
+
+  // ── credentials (api tokens) ─────────────────────────────────────────────────
+
+  async issueToken(input: {
+    name: string
+    type?: TokenType
+    organizationId?: string | null
+    userId?: string | null
+    scopes?: string[]
+    expiresAt?: number | null
+    metadata?: Record<string, unknown>
+  }): Promise<IssuedToken> {
+    return this.api<IssuedToken>('POST', '/v1/tokens', input)
+  }
+
+  async listTokens(): Promise<ApiToken[]> {
+    const { tokens } = await this.api<{ tokens: ApiToken[] }>('GET', '/v1/tokens')
+    return tokens
+  }
+
+  async revokeToken(id: string): Promise<void> {
+    await this.api('DELETE', `/v1/tokens/${encodeURIComponent(id)}`)
+  }
+
+  /** Verify a raw token secret → its principal, or throw IamError(401). */
+  async verifyToken(secret: string): Promise<TokenPrincipal> {
+    const { principal } = await this.api<{ principal: TokenPrincipal }>('POST', '/v1/tokens/verify', { token: secret })
+    return principal
+  }
+}
+
+/** Factory used by the SDK capability registry. */
+export function createIamClient(opts: IamClientOptions): IamClient {
+  return new IamClient(opts)
+}

package/src/events.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod'
+import { defineAggregate } from '@baseworks/foldbase'
+
+/**
+ * Event catalogs — the single source of truth for iam-service payloads.
+ * Shared by the service (typed emit) and tests. Two aggregates:
+ *
+ *   user       — a platform identity, keyed on (issuer, subject); id = user id
+ *   api_token   — a service/cli/agent credential; id = token id
+ *
+ * IAM is identity + credentials ONLY. Roles, memberships, orgs and the PDP live
+ * in @baseworks/org — a user has no org of their own, only memberships, so every
+ * role question is an org question (see iam-service/AGENTS.md).
+ *
+ * All timestamps are epoch millis carried in the payload (`at`) so folds stay
+ * deterministic. `scopes`/`metadata` are JSON strings the service serializes
+ * before emit (mirrors org-service's `metadata` convention).
+ */
+
+// ── user ────────────────────────────────────────────────────────────────────
+
+export const UserEvents = defineAggregate('user', {
+  // First sight of an OIDC identity (auth-service POST /sync). id = new user id.
+  UserSynced: z.object({
+    subject: z.string().min(1),
+    issuer: z.string().min(1),
+    email: z.string().min(1),
+    name: z.string().nullable(),
+    picture: z.string().nullable(),
+    at: z.number().int(),
+  }),
+  // A later /sync for the same identity refreshes the profile fields.
+  UserUpdated: z.object({
+    email: z.string().min(1),
+    name: z.string().nullable(),
+    picture: z.string().nullable(),
+    at: z.number().int(),
+  }),
+})
+
+// ── api_token ───────────────────────────────────────────────────────────────
+
+export const TOKEN_TYPES = ['user', 'service', 'cli', 'agent'] as const
+export const TokenType = z.enum(TOKEN_TYPES)
+export type TokenType = z.infer<typeof TokenType>
+
+export const ApiTokenEvents = defineAggregate('api_token', {
+  TokenIssued: z.object({
+    tokenType: TokenType,
+    // Opaque context — iam does NOT validate org membership (org owns that).
+    organizationId: z.string().nullable(),
+    userId: z.string().nullable(),
+    name: z.string().min(1),
+    tokenHash: z.string().min(1),
+    keyPrefix: z.string().min(1),
+    scopes: z.string(), // JSON string[]
+    metadata: z.string(), // JSON object
+    expiresAt: z.number().int().nullable(),
+    at: z.number().int(),
+  }),
+  // Throttled last-used stamp (not written on every request).
+  TokenUsed: z.object({
+    at: z.number().int(),
+  }),
+  // Revoke removes the read-model row; the event stays in the log.
+  TokenRevoked: z.object({}),
+})

package/src/projections.ts

@@ -0,0 +1,55 @@
+import { defineProjection, type PolicyDef } from '@baseworks/foldbase'
+import { UserEvents, ApiTokenEvents } from './events.js'
+
+/**
+ * Read-model definitions the service registers on boot (idempotent, like
+ * migrations). Columns are inferred from the event field types. `updated_at` is
+ * part of foldbase's read-model spine (server-maintained) so it is never
+ * declared; the stream id is the `id` column.
+ *
+ * The service is the authorization layer (route handlers enforce end-user
+ * scoping), so policies are permissive for the service's own `admin` identity.
+ */
+
+export const readUsers = defineProjection('users', UserEvents, (on) => ({
+  UserSynced: on.UserSynced.upsert((e) => ({
+    subject: e.subject,
+    issuer: e.issuer,
+    email: e.email,
+    name: e.name,
+    picture: e.picture,
+    created_at: e.at,
+  })),
+  UserUpdated: on.UserUpdated.upsert((e) => ({
+    email: e.email,
+    name: e.name,
+    picture: e.picture,
+  })),
+}))
+
+export const readApiTokens = defineProjection('api_tokens', ApiTokenEvents, (on) => ({
+  TokenIssued: on.TokenIssued.upsert((e) => ({
+    token_type: e.tokenType,
+    organization_id: e.organizationId,
+    user_id: e.userId,
+    name: e.name,
+    token_hash: e.tokenHash,
+    key_prefix: e.keyPrefix,
+    scopes: e.scopes,
+    metadata: e.metadata,
+    expires_at: e.expiresAt,
+    created_at: e.at,
+  })),
+  TokenUsed: on.TokenUsed.upsert((e) => ({
+    last_used_at: e.at,
+  })),
+  TokenRevoked: on.TokenRevoked.delete(),
+}))
+
+export const PROJECTIONS = [readUsers, readApiTokens] as const
+
+/** Permissive policies for the service's own `admin` identity. */
+export const POLICIES: PolicyDef[] = [
+  { name: 'users', role: 'admin' },
+  { name: 'api_tokens', role: 'admin' },
+]

package/src/types.ts

@@ -0,0 +1,96 @@
+// IAM domain types. Foldbase-native: read-model row shapes (snake_case, as
+// stored) and REST DTOs (camelCase, as the API + CLI consume them).
+
+import type { TokenType } from './events.js'
+export type { TokenType } from './events.js'
+export { TOKEN_TYPES } from './events.js'
+
+// ── read-model rows (snake_case — foldbase read_<name> tables) ────────────────
+
+export interface UserRow {
+  id: string
+  subject: string
+  issuer: string
+  email: string
+  name: string | null
+  picture: string | null
+  created_at: number
+  updated_at: number
+}
+
+export interface ApiTokenRow {
+  id: string
+  token_type: TokenType
+  organization_id: string | null
+  user_id: string | null
+  name: string
+  token_hash: string
+  key_prefix: string
+  scopes: string // JSON string[]
+  metadata: string // JSON object
+  expires_at: number | null
+  last_used_at: number | null
+  created_at: number
+  updated_at: number
+}
+
+// ── REST DTOs (camelCase — API + CLI) ─────────────────────────────────────────
+
+export interface User {
+  id: string
+  subject: string
+  issuer: string
+  email: string
+  name: string | null
+  picture: string | null
+  createdAt: number
+  updatedAt: number
+}
+
+/** Public-safe identity projection (returned by /me and /users/lookup). */
+export interface PublicUser {
+  id: string
+  email: string
+  name: string | null
+}
+
+/** An OIDC identity presented to POST /sync (before a user id exists). */
+export interface OidcIdentity {
+  subject: string
+  issuer: string
+  email: string
+  name?: string | null
+  picture?: string | null
+}
+
+/** A token as listed — never carries the secret or its hash. */
+export interface ApiToken {
+  id: string
+  type: TokenType
+  organizationId: string | null
+  userId: string | null
+  name: string
+  keyPrefix: string
+  scopes: string[]
+  metadata: Record<string, unknown>
+  expiresAt: number | null
+  lastUsedAt: number | null
+  createdAt: number
+  updatedAt: number
+}
+
+/** The one-time issue response — `token` is the secret, shown only here. */
+export interface IssuedToken {
+  token: ApiToken
+  /** The full secret; surfaced exactly once at creation. */
+  secret: string
+}
+
+/** The identity a verified token resolves to. */
+export interface TokenPrincipal {
+  tokenId: string
+  type: TokenType
+  organizationId: string | null
+  userId: string | null
+  scopes: string[]
+}