tapimo 0.1.0 → 0.3.0

package/src/apps/platform/routes/members.ts

@@ -0,0 +1,313 @@
+import { type Context, Hono } from 'hono'
+import * as z from 'zod/mini'
+
+import type * as App from '../../../App.js'
+import * as Auth from '../../../internal/Auth.js'
+import * as Db from '../../../db/Db.js'
+import * as Memberships from '../../../db/tables/memberships.js'
+import * as OpenApi from '../../../internal/OpenApi.js'
+import * as Response from '../../../internal/Response.js'
+import * as Schema from '../../../internal/Schema.js'
+import * as Users from '../../../db/tables/users.js'
+
+/** Zod schemas owned by the members resource. */
+export namespace schema {
+  /** A membership role. */
+  export const Role = z
+    .enum(Memberships.roles)
+    .check(z.describe('Membership role.'), z.meta({ examples: ['admin'] }))
+
+  /** One organization member: the membership plus the member's identity. */
+  export const Member = Schema.describe(
+    z.object({
+      address: z
+        .optional(z.string())
+        .check(
+          z.describe("The member's wallet address, when wallet sign-in established it."),
+          z.meta({ examples: ['0x20f414b3cbcf1fd8e8f5e1c1c2e3d4a5b6c7d8e9'] }),
+        ),
+      createdAt: z
+        .string()
+        .check(
+          z.describe('When the member joined (ISO 8601).'),
+          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+        ),
+      email: z
+        .optional(z.string())
+        .check(
+          z.describe("The member's verified email, when known."),
+          z.meta({ examples: ['dev@example.com'] }),
+        ),
+      role: Role,
+      userId: z
+        .string()
+        .check(
+          z.describe('Member user id (`usr_…`).'),
+          z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+        ),
+    }),
+    "One organization member: the membership plus the member's identity.",
+  )
+
+  /** Path parameters addressing an organization's member collection. */
+  export const Params = z
+    .object({
+      orgId: z
+        .string()
+        .check(
+          z.describe('The organization id (`org_…`).'),
+          z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+        ),
+    })
+    .check(z.describe("Path parameters for an organization's members."))
+
+  /** Path parameters addressing one member. */
+  export const MemberParams = z
+    .object({
+      orgId: z
+        .string()
+        .check(
+          z.describe('The organization id (`org_…`).'),
+          z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+        ),
+      userId: z
+        .string()
+        .check(
+          z.describe('The member user id (`usr_…`).'),
+          z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+        ),
+    })
+    .check(z.describe('Path parameters for one member.'))
+
+  /** Request body changing a member's role. */
+  export const MemberBody = z
+    .object({ role: Role })
+    .check(z.describe("Fields for changing a member's role."))
+
+  /** Schemas for the listMembers operation. */
+  export namespace listMembers {
+    /** Non-paginated list of an organization's members. */
+    export const Response = Schema.describe(
+      z.object({
+        data: z.array(Member).check(z.describe('The members, oldest first.')),
+      }),
+      "A non-paginated list of an organization's members.",
+    )
+  }
+
+  /** Schemas for the removeMember operation. */
+  export namespace removeMember {
+    /** Confirmation that the member was removed. */
+    export const Response = z
+      .object({
+        userId: z
+          .string()
+          .check(
+            z.describe('User id (`usr_…`) of the removed member.'),
+            z.meta({ examples: ['usr_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+          ),
+      })
+      .check(z.describe('Confirmation that the member was removed.'))
+  }
+}
+
+/**
+ * Mounts the `/orgs/:orgId/members` resource: the organization's team.
+ * Members read; owners change roles and remove members (any member may remove
+ * themself). The last owner can never be demoted or removed.
+ */
+export function members() {
+  return new Hono<App.Environment>()
+    .get(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/members',
+      Auth.policy({ session: true }),
+      Auth.ensureOrg(),
+      OpenApi.validate('param', schema.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'listMembers',
+        responses: OpenApi.responses({
+          errors: { 404: 'No accessible organization was found for this id.' },
+          success: {
+            description: 'The members, oldest first.',
+            schema: schema.listMembers.Response,
+          },
+        }),
+        summary: 'List members',
+        tags: ['Members'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+
+        const db = Db.get(c.get('db'))
+        try {
+          const records = await Memberships.listByOrgDetailed(db, Auth.org(c).id)
+          return c.json(
+            Response.validated(schema.listMembers.Response, {
+              data: records.map(serializeMember),
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .patch(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/members/:userId{usr_[A-Za-z0-9_-]+}',
+      Auth.policy({ session: true }),
+      Auth.ensureOrg({ role: 'owner' }),
+      OpenApi.validate('param', schema.MemberParams, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.validate('json', schema.MemberBody, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: "Change a member's role. The last owner cannot be demoted.",
+        operationId: 'updateMember',
+        responses: OpenApi.responses({
+          errors: {
+            404: 'No accessible member was found for this id.',
+            409: {
+              codes: ['last_owner'],
+              description: 'The organization would be left without an owner.',
+            },
+          },
+          success: { description: 'The updated member.', schema: schema.Member },
+        }),
+        summary: 'Update member',
+        tags: ['Members'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'body_invalid',
+            message: 'Check the request body and try again.',
+          })
+
+        const { userId } = c.req.valid('param')
+        const body = c.req.valid('json')
+        const db = Db.get(c.get('db'))
+        try {
+          const result = await Memberships.update(db, Auth.org(c).id, userId, { role: body.role })
+          if (result.error === 'last_owner') return lastOwner(c)
+          if (result.error) return memberNotFound(c)
+          const user = await Users.get(db, userId)
+          if (!user) return memberNotFound(c)
+          return c.json(
+            Response.validated(
+              schema.Member,
+              serializeMember({ ...result.record, address: user.address, email: user.email }),
+            ),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .delete(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/members/:userId{usr_[A-Za-z0-9_-]+}',
+      Auth.policy({ session: true }),
+      Auth.ensureOrg(),
+      OpenApi.validate('param', schema.MemberParams, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        description: 'Remove a member. Owners remove anyone; any member removes themself. The last owner cannot be removed.', // prettier-ignore
+        operationId: 'removeMember',
+        responses: OpenApi.responses({
+          errors: {
+            404: 'No accessible member was found for this id.',
+            409: {
+              codes: ['last_owner'],
+              description: 'The organization would be left without an owner.',
+            },
+          },
+          success: {
+            description: 'Confirmation that the member was removed.',
+            schema: schema.removeMember.Response,
+          },
+        }),
+        summary: 'Remove member',
+        tags: ['Members'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+
+        const { userId } = c.req.valid('param')
+        // Owners remove anyone; everyone else only themself (leaving the org).
+        const caller = Auth.membership(c)
+        if (caller && caller.role !== 'owner' && caller.userId !== userId)
+          return Response.error(c, {
+            code: 'forbidden',
+            message: 'Requires the owner role',
+            status: 403,
+          })
+
+        const db = Db.get(c.get('db'))
+        try {
+          const result = await Memberships.remove(db, Auth.org(c).id, userId)
+          if (result === 'last_owner') return lastOwner(c)
+          if (result === 'not_found') return memberNotFound(c)
+          return c.json(Response.validated(schema.removeMember.Response, { userId }), 200)
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+}
+
+/** Projects a detailed membership row onto the member shape. */
+function serializeMember(
+  record: Memberships.Record & { address: string | null; email: string | null },
+) {
+  return {
+    ...(record.address === null ? {} : { address: record.address }),
+    createdAt: record.createdAt,
+    ...(record.email === null ? {} : { email: record.email }),
+    role: record.role,
+    userId: record.userId,
+  }
+}
+
+function lastOwner(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'last_owner',
+    message: 'The organization would be left without an owner',
+    status: 409,
+  })
+}
+
+function memberNotFound(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'member_not_found',
+    message: 'Member not found',
+    status: 404,
+  })
+}

package/src/apps/platform/routes/orgs.test.ts

@@ -0,0 +1,313 @@
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
+
+import * as TestApp from '../../../../test/App.js'
+import * as Organizations from '../../../db/tables/organizations.js'
+import * as Projects from '../../../db/tables/projects.js'
+import type * as Log from '../../../internal/Log.js'
+import * as Orgs from './orgs.js'
+
+/** Origin pinned for SIWE domain binding; Hono test requests use this host. */
+const origin = 'http://localhost'
+
+/** Super admin secret configured on the test app. */
+const secret = 'tempo:sk:b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1'
+
+/** Wildcard-scoped key: full data access, still not a super admin. */
+const wildcard = {
+  id: 'key_wildcard',
+  orgId: 'org_test',
+  scopes: ['*'],
+  token: 'secret_wildcard_key',
+} satisfies TestApp.kvStore.Key
+
+/** RequestInit presenting the given token. */
+function as(token: string) {
+  return { headers: { 'tempo-api-key': token } } as const
+}
+
+/** RequestInit for a JSON mutation carrying the session cookie. */
+function json(method: 'PATCH' | 'POST', cookie: string, body: unknown) {
+  return {
+    body: JSON.stringify(body),
+    headers: { 'content-type': 'application/json', cookie },
+    method,
+  }
+}
+
+function createApp(db = TestApp.database()) {
+  return TestApp.create({
+    auth: { keys: [TestApp.key, wildcard], superAdmin: { secret } },
+    db,
+    session: { wallet: { origin } },
+  })
+}
+
+/** App over a database seeded with two organizations created by the super admin. */
+async function seeded() {
+  const db = TestApp.database()
+  await Organizations.create(db, { id: 'org_a', name: 'Org A' })
+  await Organizations.create(db, { id: 'org_b', name: 'Org B' })
+  return createApp(db)
+}
+
+/** Signs in a fresh scripted account; returns its session cookie. */
+async function session(app: TestApp.signIn.App) {
+  const account = privateKeyToAccount(generatePrivateKey())
+  const { cookie } = await TestApp.signIn(app, account)
+  return cookie!
+}
+
+describe('GET /orgs', () => {
+  test('lists all organizations for the super admin', async () => {
+    const response = await (await seeded()).request('/v1/orgs', as(secret))
+    expect(response.status).toBe(200)
+    const body = await TestApp.json(response, Orgs.schema.listOrganizations.Response)
+    // Timestamps are nondeterministic; two same-millisecond rows make the
+    // newest-first order itself unstable, so sort by id before snapshotting.
+    const data = body.data
+      .map(({ id, name }) => ({ id, name }))
+      .sort((a, b) => a.id.localeCompare(b.id))
+    expect(data).toMatchInlineSnapshot(`
+      [
+        {
+          "id": "org_a",
+          "name": "Org A",
+        },
+        {
+          "id": "org_b",
+          "name": "Org B",
+        },
+      ]
+    `)
+  })
+
+  test('lists only owned organizations for a session', async () => {
+    const app = await seeded()
+    const cookie = await session(app)
+
+    const empty = await app.request('/v1/orgs', { headers: { cookie } })
+    expect(empty.status).toBe(200)
+    expect((await TestApp.json(empty, Orgs.schema.listOrganizations.Response)).data).toEqual([])
+
+    const created = await app.request('/v1/orgs', json('POST', cookie, { name: 'Acme' }))
+    expect(created.status).toBe(200)
+
+    const listed = await app.request('/v1/orgs', { headers: { cookie } })
+    const body = await TestApp.json(listed, Orgs.schema.listOrganizations.Response)
+    expect(body.data.map(({ name }) => name)).toEqual(['Acme'])
+  })
+
+  test('rejects missing credentials', async () => {
+    const response = await (await seeded()).request('/v1/orgs')
+    expect(response.status).toBe(401)
+    const { requestId, ...body } = (await response.json()) as { requestId?: string }
+    expect(requestId).toBeDefined()
+    expect(body).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "api_key_missing",
+          "message": "Missing API key",
+        },
+      }
+    `)
+  })
+
+  test('rejects API keys without the wildcard scope', async () => {
+    const response = await (await seeded()).request('/v1/orgs', as(TestApp.key.token))
+    expect(response.status).toBe(403)
+  })
+
+  test('rejects wildcard API keys', async () => {
+    const response = await (await seeded()).request('/v1/orgs', as(wildcard.token))
+    expect(response.status).toBe(403)
+    const { requestId, ...body } = (await response.json()) as { requestId?: string }
+    expect(requestId).toBeDefined()
+    expect(body).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "forbidden",
+          "message": "API key not permitted for this route",
+        },
+      }
+    `)
+  })
+
+  test('rejects the secret when super admin is unconfigured', async () => {
+    const client = TestApp.client({ db: TestApp.database() })
+    const response = await client.v1.orgs.$get({}, as(secret))
+    expect(response.status).toBe(401)
+  })
+
+  test('logs the super admin actor, never the secret', async () => {
+    const entries: Log.Entry[] = []
+    const client = TestApp.client({
+      auth: { superAdmin: { secret } },
+      db: TestApp.database(),
+      logger: (entry) => {
+        entries.push(entry)
+      },
+    })
+    await client.v1.orgs.$get({}, as(secret))
+
+    expect(entries[0]?.principal).toMatchInlineSnapshot(`
+      {
+        "actor": "super_admin",
+        "id": "super_admin",
+        "type": "super_admin",
+      }
+    `)
+    expect(JSON.stringify(entries)).not.toContain(secret)
+  })
+})
+
+describe('POST /orgs', () => {
+  test('creates a session-owned organization', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+
+    const response = await app.request('/v1/orgs', json('POST', cookie, { name: 'Acme' }))
+    expect(response.status).toBe(200)
+    const body = await TestApp.json(response, Orgs.schema.Organization)
+    expect(body.id.startsWith('org_')).toBe(true)
+    expect(body.name).toBe('Acme')
+  })
+
+  test('creates a memberless org as the super admin', async () => {
+    const app = createApp()
+    const response = await app.request('/v1/orgs', {
+      body: JSON.stringify({ name: 'Ops' }),
+      headers: { 'content-type': 'application/json', 'tempo-api-key': secret },
+      method: 'POST',
+    })
+    expect(response.status).toBe(200)
+    const org = await TestApp.json(response, Orgs.schema.Organization)
+    expect(org.name).toBe('Ops')
+
+    // Memberless: invisible to sessions until an owner is seated.
+    const cookie = await session(app)
+    const foreign = await app.request(`/v1/orgs/${org.id}`, { headers: { cookie } })
+    expect(foreign.status).toBe(404)
+    const superAdmin = await app.request(`/v1/orgs/${org.id}`, as(secret))
+    expect(superAdmin.status).toBe(200)
+  })
+
+  test('rejects invalid bodies', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const response = await app.request('/v1/orgs', json('POST', cookie, { name: '' }))
+    expect(response.status).toBe(400)
+  })
+})
+
+describe('GET /orgs/:orgId', () => {
+  test('hides foreign organizations behind 404', async () => {
+    const app = createApp()
+    const owner = await session(app)
+    const created = await app.request('/v1/orgs', json('POST', owner, { name: 'Acme' }))
+    const org = await TestApp.json(created, Orgs.schema.Organization)
+
+    const owned = await app.request(`/v1/orgs/${org.id}`, { headers: { cookie: owner } })
+    expect(owned.status).toBe(200)
+
+    const stranger = await session(app)
+    const foreign = await app.request(`/v1/orgs/${org.id}`, { headers: { cookie: stranger } })
+    expect(foreign.status).toBe(404)
+
+    const superAdmin = await app.request(`/v1/orgs/${org.id}`, as(secret))
+    expect(superAdmin.status).toBe(200)
+  })
+})
+
+describe('PATCH /orgs/:orgId', () => {
+  test('renames an owned organization', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const created = await app.request('/v1/orgs', json('POST', cookie, { name: 'Acme' }))
+    const org = await TestApp.json(created, Orgs.schema.Organization)
+
+    const renamed = await app.request(`/v1/orgs/${org.id}`, json('PATCH', cookie, { name: 'Acme, Inc.' })) // prettier-ignore
+    expect(renamed.status).toBe(200)
+    expect((await TestApp.json(renamed, Orgs.schema.Organization)).name).toBe('Acme, Inc.')
+
+    const stranger = await session(app)
+    const foreign = await app.request(`/v1/orgs/${org.id}`, json('PATCH', stranger, { name: 'Hijack' })) // prettier-ignore
+    expect(foreign.status).toBe(404)
+  })
+})
+
+describe('DELETE /orgs/:orgId', () => {
+  test('deletes an owned organization and cascades its projects', async () => {
+    const db = TestApp.database()
+    const app = createApp(db)
+    const cookie = await session(app)
+    const created = await app.request('/v1/orgs', json('POST', cookie, { name: 'Acme' }))
+    const org = await TestApp.json(created, Orgs.schema.Organization)
+    const createdProject = await app.request(
+      `/v1/orgs/${org.id}/projects`,
+      json('POST', cookie, { name: 'Checkout' }),
+    )
+    expect(createdProject.status).toBe(200)
+    const project = (await createdProject.json()) as { id: string }
+
+    const deleted = await app.request(`/v1/orgs/${org.id}`, {
+      headers: { cookie },
+      method: 'DELETE',
+    })
+    expect(deleted.status).toBe(200)
+    expect(await TestApp.json(deleted, Orgs.schema.deleteOrganization.Response)).toEqual({
+      id: org.id,
+    })
+
+    const gone = await app.request(`/v1/orgs/${org.id}`, { headers: { cookie } })
+    expect(gone.status).toBe(404)
+    // Cascade: the org's project rows are deleted, not orphaned.
+    expect(await Projects.get(db, project.id)).toBeUndefined()
+  })
+
+  test('hides foreign organizations behind 404', async () => {
+    const app = createApp()
+    const owner = await session(app)
+    const created = await app.request('/v1/orgs', json('POST', owner, { name: 'Acme' }))
+    const org = await TestApp.json(created, Orgs.schema.Organization)
+
+    const stranger = await session(app)
+    const foreign = await app.request(`/v1/orgs/${org.id}`, {
+      headers: { cookie: stranger },
+      method: 'DELETE',
+    })
+    expect(foreign.status).toBe(404)
+
+    const still = await app.request(`/v1/orgs/${org.id}`, { headers: { cookie: owner } })
+    expect(still.status).toBe(200)
+  })
+
+  test('deletes any organization as the super admin', async () => {
+    const app = await seeded()
+    const response = await app.request('/v1/orgs/org_a', { ...as(secret), method: 'DELETE' })
+    expect(response.status).toBe(200)
+
+    const gone = await app.request('/v1/orgs/org_a', as(secret))
+    expect(gone.status).toBe(404)
+  })
+})
+
+describe('ownership', () => {
+  test('hides organizations without owning users from every session verb', async () => {
+    const app = await seeded()
+    const cookie = await session(app)
+
+    const read = await app.request('/v1/orgs/org_a', { headers: { cookie } })
+    expect(read.status).toBe(404)
+
+    const renamed = await app.request('/v1/orgs/org_a', json('PATCH', cookie, { name: 'Steal' }))
+    expect(renamed.status).toBe(404)
+
+    const deleted = await app.request('/v1/orgs/org_a', { headers: { cookie }, method: 'DELETE' })
+    expect(deleted.status).toBe(404)
+
+    // Untouched by the attempts, and still visible to the super admin.
+    const superAdmin = await app.request('/v1/orgs/org_a', as(secret))
+    expect(superAdmin.status).toBe(200)
+    expect((await TestApp.json(superAdmin, Orgs.schema.Organization)).name).toBe('Org A')
+  })
+})