@baseworks/iam 0.2.0 → 1.2.0

package/dist/cli.js

@@ -39,7 +39,7 @@ 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" }
       ])
     );
@@ -48,7 +48,7 @@ function buildIamCommand(deps) {
     const res = await http.post("/v1/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}`);

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/package.json

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

package/src/__tests__/cli.test.ts

@@ -44,7 +44,7 @@ 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 }],
+      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,7 +54,7 @@ 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('/v1/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')

package/src/cli.ts

@@ -67,7 +67,7 @@ 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 }> }>(
+        .get<{ tokens: Array<{ id: string; name: string; type: string; key_prefix: string; expires_at: number | null }> }>(
           '/v1/tokens',
         )
         .catch(die)
@@ -75,7 +75,7 @@ export function buildIamCommand(deps: IamCliDeps): Command {
         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 +89,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 }>('/v1/tokens', {
           name,
           type: opts.type,
-          organizationId: opts.org ?? null,
+          org_id: opts.org ?? null,
           scopes: opts.scope ?? [],
         })
         .catch(die)

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
 }