@baseworks/iam 0.2.0 → 1.3.0

package/dist/cli.js

@@ -17,21 +17,10 @@ function buildIamCommand(deps) {
       ["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"
+      "/tokens"
     ).catch(die);
     printOutput(
       tokens,
@@ -39,16 +28,16 @@ function buildIamCommand(deps) {
       () => table(tokens, [
         { key: "name", label: "NAME" },
         { key: "type", label: "TYPE" },
-        { key: "keyPrefix", label: "PREFIX" },
+        { key: "key_prefix", 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", {
+    const res = await http.post("/tokens", {
       name,
       type: opts.type,
-      organizationId: opts.org ?? null,
+      org_id: opts.org ?? null,
       scopes: opts.scope ?? []
     }).catch(die);
     success(`token issued: ${res.token.id}`);
@@ -58,7 +47,7 @@ function buildIamCommand(deps) {
     ]);
   });
   token.command("revoke <id>").description("revoke a token by id").action(async (id) => {
-    await http.del(`/v1/tokens/${encodeURIComponent(id)}`).catch(die);
+    await http.del(`/tokens/${encodeURIComponent(id)}`).catch(die);
     success(`token revoked: ${id}`);
   });
   return iam;

package/dist/client.d.ts

@@ -35,8 +35,8 @@ interface User {
     email: string;
     name: string | null;
     picture: string | null;
-    createdAt: number;
-    updatedAt: number;
+    created_at: number;
+    updated_at: number;
 }
 /** Public-safe identity projection (returned by /me and /users/lookup). */
 interface PublicUser {
@@ -56,16 +56,16 @@ interface OidcIdentity {
 interface ApiToken {
     id: string;
     type: TokenType;
-    organizationId: string | null;
-    userId: string | null;
+    org_id: string | null;
+    user_id: string | null;
     name: string;
-    keyPrefix: string;
+    key_prefix: string;
     scopes: string[];
     metadata: Record<string, unknown>;
-    expiresAt: number | null;
-    lastUsedAt: number | null;
-    createdAt: number;
-    updatedAt: number;
+    expires_at: number | null;
+    last_used_at: number | null;
+    created_at: number;
+    updated_at: number;
 }
 /** The one-time issue response — `token` is the secret, shown only here. */
 interface IssuedToken {
@@ -75,11 +75,21 @@ interface IssuedToken {
 }
 /** The identity a verified token resolves to. */
 interface TokenPrincipal {
-    tokenId: string;
+    token_id: string;
     type: TokenType;
-    organizationId: string | null;
-    userId: string | null;
+    org_id: string | null;
+    user_id: string | null;
     scopes: string[];
+    /** The name it was issued under, e.g. `notes-api@staging`. */
+    name: string;
+    /**
+     * What the issuer bound the token to, returned as it was stored. A service
+     * that issues tokens for its own workloads keeps the binding here (for
+     * example the scope and app a runtime token belongs to) and checks it on
+     * every verify, because iam keeps it opaque and never interprets it.
+     */
+    metadata: Record<string, unknown>;
+    expires_at: number | null;
 }
 
 /** Forwarded end-user identity (X-Auth-*) for a trusted service caller. */
@@ -135,16 +145,29 @@ declare class IamClient {
     }>;
     /** Resolve a user id by exact email (invite flows). */
     lookupByEmail(email: string): Promise<PublicUser>;
+    /**
+     * Resolve a list of user ids to public profiles, in one round trip.
+     *
+     * Ids that resolve to nobody are absent from the answer rather than an error:
+     * one deleted user must not break a page that is otherwise fine.
+     */
+    resolveUsers(ids: string[]): Promise<PublicUser[]>;
     issueToken(input: {
         name: string;
         type?: TokenType;
-        organizationId?: string | null;
-        userId?: string | null;
+        org_id?: string | null;
+        user_id?: string | null;
         scopes?: string[];
-        expiresAt?: number | null;
+        expires_at?: number | null;
         metadata?: Record<string, unknown>;
     }): Promise<IssuedToken>;
-    listTokens(): Promise<ApiToken[]>;
+    /**
+     * The caller's own tokens, or with `org_id` an organisation's — the latter
+     * only for a service named in the realm's IAM_ORG_TOKEN_ISSUERS.
+     */
+    listTokens(opts?: {
+        org_id?: string;
+    }): Promise<ApiToken[]>;
     revokeToken(id: string): Promise<void>;
     /** Verify a raw token secret → its principal, or throw IamError(401). */
     verifyToken(secret: string): Promise<TokenPrincipal>;

package/dist/client.js

@@ -77,20 +77,36 @@ var IamClient = class _IamClient {
     const { user } = await this.api("GET", `/users/lookup?email=${encodeURIComponent(email)}`);
     return user;
   }
+  /**
+   * Resolve a list of user ids to public profiles, in one round trip.
+   *
+   * Ids that resolve to nobody are absent from the answer rather than an error:
+   * one deleted user must not break a page that is otherwise fine.
+   */
+  async resolveUsers(ids) {
+    if (ids.length === 0) return [];
+    const { users } = await this.api("POST", "/users/resolve", { ids });
+    return users;
+  }
   // ── credentials (api tokens) ─────────────────────────────────────────────────
   async issueToken(input) {
-    return this.api("POST", "/v1/tokens", input);
+    return this.api("POST", "/tokens", input);
   }
-  async listTokens() {
-    const { tokens } = await this.api("GET", "/v1/tokens");
+  /**
+   * The caller's own tokens, or with `org_id` an organisation's — the latter
+   * only for a service named in the realm's IAM_ORG_TOKEN_ISSUERS.
+   */
+  async listTokens(opts = {}) {
+    const q = opts.org_id ? `?${new URLSearchParams({ org_id: opts.org_id })}` : "";
+    const { tokens } = await this.api("GET", `/tokens${q}`);
     return tokens;
   }
   async revokeToken(id) {
-    await this.api("DELETE", `/v1/tokens/${encodeURIComponent(id)}`);
+    await this.api("DELETE", `/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 });
+    const { principal } = await this.api("POST", "/tokens/verify", { token: secret });
     return principal;
   }
 };

package/dist/events.d.ts

@@ -25,17 +25,17 @@ declare const UserEvents: _baseworks_foldbase.EventCatalog<{
         picture: z.ZodNullable<z.ZodString>;
         at: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
-        email: string;
         at: number;
         subject: string;
         issuer: string;
+        email: string;
         name: string | null;
         picture: string | null;
     }, {
-        email: string;
         at: number;
         subject: string;
         issuer: string;
+        email: string;
         name: string | null;
         picture: string | null;
     }>;
@@ -45,13 +45,13 @@ declare const UserEvents: _baseworks_foldbase.EventCatalog<{
         picture: z.ZodNullable<z.ZodString>;
         at: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
-        email: string;
         at: number;
+        email: string;
         name: string | null;
         picture: string | null;
     }, {
-        email: string;
         at: number;
+        email: string;
         name: string | null;
         picture: string | null;
     }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baseworks/iam",
-  "version": "0.2.0",
+  "version": "1.3.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": {

package/src/__tests__/cli.test.ts

@@ -27,15 +27,12 @@ describe('flect iam whoami', () => {
   })
 })
 
-// ── users find ────────────────────────────────────────────────────────────────
+// ── no users find ─────────────────────────────────────────────────────────────
 
-describe('flect iam users find', () => {
-  it('resolves a user id by email', async () => {
-    mocks.mockGet('/users/lookup', { user: USER })
+describe('flect iam users', () => {
+  it('is gone: looking a person up by email is for services, not for a CLI', async () => {
     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')
+    expect(r.stdout + r.stderr).toMatch(/unknown command/)
   })
 })
 
@@ -43,8 +40,8 @@ describe('flect iam users find', () => {
 
 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 }],
+    mocks.mockGet('/tokens', {
+      tokens: [{ id: 't1', name: 'ci', type: 'service', key_prefix: 'bwt_abc12345', expires_at: null }],
     })
     const r = await run(['iam', 'token', 'list'])
     expect(r.exitCode).toBe(0)
@@ -54,14 +51,14 @@ describe('flect iam token', () => {
   })
 
   it('issue prints the one-time secret', async () => {
-    mocks.mockPost('/v1/tokens', { token: { id: 't1', keyPrefix: 'bwt_secret1234' }, secret: 'bwt_secret1234_rest' })
+    mocks.mockPost('/tokens', { token: { id: 't1', key_prefix: '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')
+    mocks.mockDelete('/tokens/t1')
     const r = await run(['iam', 'token', 'revoke', 't1'])
     expect(r.exitCode).toBe(0)
     expect(r.stdout).toContain('t1')

package/src/cli.ts

@@ -41,24 +41,11 @@ export function buildIamCommand(deps: IamCliDeps): Command {
       ])
     })
 
-  // ── 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 ?? '—'],
-      ])
-    })
+  // There is no `users find <email>`. It asked iam "does this address have an
+  // account here?" with a person's token, which is an account-existence oracle;
+  // iam answers that to services only now. Invite by email instead
+  // (`org invite <email>`): the invitation reaches the person without anyone
+  // learning their user id first.
 
   // ── token (credentials) ───────────────────────────────────────────────────--
   const token = iam.command('token').description('api tokens (service / cli / agent credentials)')
@@ -67,15 +54,15 @@ export function buildIamCommand(deps: IamCliDeps): Command {
     .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',
+        .get<{ tokens: Array<{ id: string; name: string; type: string; key_prefix: string; expires_at: number | null }> }>(
+          '/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: 'key_prefix', label: 'PREFIX' },
           { key: 'id', label: 'ID' },
         ]),
       )
@@ -89,10 +76,10 @@ export function buildIamCommand(deps: IamCliDeps): Command {
     .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', {
+        .post<{ token: { id: string; key_prefix: string }; secret: string }>('/tokens', {
           name,
           type: opts.type,
-          organizationId: opts.org ?? null,
+          org_id: opts.org ?? null,
           scopes: opts.scope ?? [],
         })
         .catch(die)
@@ -107,7 +94,7 @@ export function buildIamCommand(deps: IamCliDeps): Command {
     .command('revoke <id>')
     .description('revoke a token by id')
     .action(async (id: string) => {
-      await http.del(`/v1/tokens/${encodeURIComponent(id)}`).catch(die)
+      await http.del(`/tokens/${encodeURIComponent(id)}`).catch(die)
       success(`token revoked: ${id}`)
     })
 

package/src/client.ts

@@ -130,32 +130,49 @@ export class IamClient {
     return user
   }
 
+  /**
+   * Resolve a list of user ids to public profiles, in one round trip.
+   *
+   * Ids that resolve to nobody are absent from the answer rather than an error:
+   * one deleted user must not break a page that is otherwise fine.
+   */
+  async resolveUsers(ids: string[]): Promise<PublicUser[]> {
+    if (ids.length === 0) return []
+    const { users } = await this.api<{ users: PublicUser[] }>('POST', '/users/resolve', { ids })
+    return users
+  }
+
   // ── credentials (api tokens) ─────────────────────────────────────────────────
 
   async issueToken(input: {
     name: string
     type?: TokenType
-    organizationId?: string | null
-    userId?: string | null
+    org_id?: string | null
+    user_id?: string | null
     scopes?: string[]
-    expiresAt?: number | null
+    expires_at?: number | null
     metadata?: Record<string, unknown>
   }): Promise<IssuedToken> {
-    return this.api<IssuedToken>('POST', '/v1/tokens', input)
+    return this.api<IssuedToken>('POST', '/tokens', input)
   }
 
-  async listTokens(): Promise<ApiToken[]> {
-    const { tokens } = await this.api<{ tokens: ApiToken[] }>('GET', '/v1/tokens')
+  /**
+   * The caller's own tokens, or with `org_id` an organisation's — the latter
+   * only for a service named in the realm's IAM_ORG_TOKEN_ISSUERS.
+   */
+  async listTokens(opts: { org_id?: string } = {}): Promise<ApiToken[]> {
+    const q = opts.org_id ? `?${new URLSearchParams({ org_id: opts.org_id })}` : ''
+    const { tokens } = await this.api<{ tokens: ApiToken[] }>('GET', `/tokens${q}`)
     return tokens
   }
 
   async revokeToken(id: string): Promise<void> {
-    await this.api('DELETE', `/v1/tokens/${encodeURIComponent(id)}`)
+    await this.api('DELETE', `/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 })
+    const { principal } = await this.api<{ principal: TokenPrincipal }>('POST', '/tokens/verify', { token: secret })
     return principal
   }
 }

package/src/types.ts

@@ -34,7 +34,11 @@ export interface ApiTokenRow {
   updated_at: number
 }
 
-// ── REST DTOs (camelCase — API + CLI) ─────────────────────────────────────────
+// ── REST DTOs ─────────────────────────────────────────────────────────────────
+//
+// snake_case on the wire (ADR-043), matching the row names above. The mapping
+// from row to DTO now only does real work — parsing JSON columns, hiding the
+// hash — instead of also renaming every field.
 
 export interface User {
   id: string
@@ -43,8 +47,8 @@ export interface User {
   email: string
   name: string | null
   picture: string | null
-  createdAt: number
-  updatedAt: number
+  created_at: number
+  updated_at: number
 }
 
 /** Public-safe identity projection (returned by /me and /users/lookup). */
@@ -67,16 +71,16 @@ export interface OidcIdentity {
 export interface ApiToken {
   id: string
   type: TokenType
-  organizationId: string | null
-  userId: string | null
+  org_id: string | null
+  user_id: string | null
   name: string
-  keyPrefix: string
+  key_prefix: string
   scopes: string[]
   metadata: Record<string, unknown>
-  expiresAt: number | null
-  lastUsedAt: number | null
-  createdAt: number
-  updatedAt: number
+  expires_at: number | null
+  last_used_at: number | null
+  created_at: number
+  updated_at: number
 }
 
 /** The one-time issue response — `token` is the secret, shown only here. */
@@ -88,9 +92,19 @@ export interface IssuedToken {
 
 /** The identity a verified token resolves to. */
 export interface TokenPrincipal {
-  tokenId: string
+  token_id: string
   type: TokenType
-  organizationId: string | null
-  userId: string | null
+  org_id: string | null
+  user_id: string | null
   scopes: string[]
+  /** The name it was issued under, e.g. `notes-api@staging`. */
+  name: string
+  /**
+   * What the issuer bound the token to, returned as it was stored. A service
+   * that issues tokens for its own workloads keeps the binding here (for
+   * example the scope and app a runtime token belongs to) and checks it on
+   * every verify, because iam keeps it opaque and never interprets it.
+   */
+  metadata: Record<string, unknown>
+  expires_at: number | null
 }