tapimo 0.0.2 → 0.2.0

package/src/apps/platform/App.ts

@@ -0,0 +1,130 @@
+import { Hono } from 'hono'
+
+import type * as App from '../../App.js'
+import * as Metadata from '../metadata.js'
+
+import { apiKeys } from './routes/api-keys.js'
+import { invitations } from './routes/invitations.js'
+import { me } from './routes/me.js'
+import { members } from './routes/members.js'
+import { orgs } from './routes/orgs.js'
+import { projects } from './routes/projects.js'
+
+/**
+ * Minimal transactional email sender. Cloudflare deployments wrap the Email
+ * Service binding (`{ from, send: (m) => env.EMAIL.send(m) }`); other hosts
+ * pass any compatible sender. Dispatch is always best-effort.
+ */
+export type Email = {
+  /** Console URL embedded in email links (e.g. sign-in URLs). Defaults to the hosted console; self-hosts point it at their own. */
+  consoleUrl?: string | undefined
+  /** Sender address for platform emails (e.g. `noreply@tempo.xyz`). */
+  from: string
+  /** Sends one message. */
+  send: (message: Email.Message) => Promise<unknown>
+}
+
+export declare namespace Email {
+  /** One transactional message. */
+  type Message = {
+    /** Sender address. */
+    from: string
+    /** HTML body. */
+    html?: string | undefined
+    /** Subject line. */
+    subject: string
+    /** Plain-text body. */
+    text: string
+    /** Recipient address. */
+    to: string
+  }
+}
+
+/**
+ * Request environment for platform routes: the shared app environment plus the
+ * `email` sender this group publishes on context. Owned here, not in core
+ * `App.Environment`, since email is a platform concern.
+ */
+export type Environment = {
+  Variables: App.Environment['Variables'] & {
+    /** Transactional email sender for platform emails; undefined when dispatch is disabled. */
+    email: Email | undefined
+  }
+}
+
+/**
+ * The tenant-platform route group: the current user, orgs, projects, members,
+ * invitations, and API-key management. Every route reads its dependencies from
+ * request context set by {@link App.create}.
+ *
+ * The session-auth surface (`/v1/auth/siwe` + `session` capability) is owned by
+ * {@link App.create}, so platform routes gate on a session without owning it.
+ *
+ * ```ts
+ * App.create(options).route('/', platform())
+ * ```
+ */
+export function platform(options: platform.Options = {}) {
+  const app = new Hono<Environment>()
+    // Publish the transactional email sender for this group's handlers
+    // (invitations read it off context); undefined disables dispatch.
+    .use('*', async (c, next) => {
+      c.set('email', options.email)
+      await next()
+    })
+    .route('/', apiKeys({ enabled: options.apiKeys !== false }))
+    .route('/', invitations())
+    .route('/', me())
+    .route('/', members())
+    .route('/', orgs())
+    .route('/', projects())
+  return Metadata.attach(app, openapi)
+}
+
+export declare namespace platform {
+  /** Options for the platform route group. */
+  type Options = {
+    /** Expose the API-key management routes in the OpenAPI document. @default true */
+    apiKeys?: boolean | undefined
+    /** Transactional email sender for platform emails (e.g. invitations); omit to disable dispatch — notified flows still work in-product. */
+    email?: Email | undefined
+  }
+}
+
+/**
+ * The OpenAPI metadata this group owns: platform operation tags and the
+ * `session` security scheme. Tagged onto the {@link platform} instance so
+ * `App.create` collects it.
+ */
+const openapi = {
+  securitySchemes: {
+    session: {
+      description: 'Cookie session established by sign-in (`POST /v1/auth/siwe`). Clients may also send the session token as `Authorization: Bearer <token>`.', // prettier-ignore
+      in: 'cookie',
+      name: 'accounts_auth',
+      type: 'apiKey',
+    },
+  },
+  tags: [
+    { name: 'API Keys', description: 'Credentials for accessing the Tempo API.' },
+    { name: 'Invitations', description: 'Pending organization invitations.' },
+    { name: 'Members', description: 'Organization team membership.' },
+    { name: 'Organizations', description: 'Teams that own application workspaces and members.' },
+    { name: 'Projects', description: 'Application workspaces within an organization.' },
+    { name: 'Users', description: 'Users on the Tempo Platform.' },
+  ],
+  'x-tagGroups': [
+    {
+      name: 'Platform API',
+      tags: [
+        'API Keys',
+        'Authentication',
+        'Invitations',
+        'Members',
+        'Organizations',
+        'Projects',
+        'Users',
+      ],
+    },
+  ],
+} satisfies App.create.Metadata

package/src/apps/platform/index.ts

@@ -0,0 +1 @@
+export { platform } from './App.js'

package/src/apps/platform/routes/api-keys.test.ts

@@ -0,0 +1,330 @@
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
+
+import * as TestApp from '../../../../test/App.js'
+import * as Keys from './api-keys.js'
+import * as Orgs from './orgs.js'
+import * as Projects from './projects.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:c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2c2'
+
+/** 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,
+  }
+}
+
+/** RequestInit for a JSON mutation authenticated as the super admin. */
+function superAdminJson(method: 'PATCH' | 'POST', body: unknown) {
+  return {
+    body: JSON.stringify(body),
+    headers: { 'content-type': 'application/json', 'tempo-api-key': secret },
+    method,
+  }
+}
+
+// Resolve-cache disabled so revocation assertions observe the store directly.
+type State = ReturnType<typeof TestApp.kvStore>
+
+function createApp(options: { kv?: { store: State } } = {}) {
+  return TestApp.create({
+    auth: { cache: false, superAdmin: { secret } },
+    ...(options.kv ? { kv: options.kv } : {}),
+    session: { wallet: { origin } },
+  })
+}
+
+function failRecordDeletes(store: State) {
+  const delete_ = store.delete.bind(store)
+  store.delete = async (key) => {
+    if (key.startsWith('apikey:')) throw new Error('KV delete failed.')
+    await delete_(key)
+  }
+}
+
+/** 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!
+}
+
+/** Creates an org and a project owned by the session. */
+async function fixture(app: ReturnType<typeof createApp>, cookie: string) {
+  const org = await TestApp.json(
+    await app.request('/v1/orgs', json('POST', cookie, { name: 'Acme' })),
+    Orgs.schema.Organization,
+  )
+  const project = await TestApp.json(
+    await app.request(`/v1/orgs/${org.id}/projects`, json('POST', cookie, { name: 'Checkout' })),
+    Projects.schema.Project,
+  )
+  return { org, project }
+}
+
+describe('keys', () => {
+  test('mints, lists, authenticates, and revokes a project key', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+    const base = `/v1/orgs/${org.id}/projects/${project.id}/api-keys`
+
+    // Scoped keys mint through the super admin: no scope is self-issuable.
+    const minted = await app.request(
+      base,
+      superAdminJson('POST', { environment: 'sandbox', name: 'CI', scopes: ['data:read'] }),
+    )
+    expect(minted.status).toBe(200)
+    const created = await TestApp.json(minted, Keys.schema.createApiKey.Response)
+    expect(created.id).toMatch(/^key_/)
+    expect(created.token).toMatch(/^tempo_sandbox:sk:[a-f0-9]{48}$/)
+    expect(created.orgId).toBe(org.id)
+    expect(created.projectId).toBe(project.id)
+    expect(created.createdBy).toBe('super_admin')
+
+    // The minted key authenticates data API requests. `no-store` forces an
+    // origin pass — an edge-cache hit would skip auth and mask the assertion.
+    const data = await app.request('/v1/tokens', {
+      headers: { 'cache-control': 'no-store', 'tempo-api-key': created.token },
+    })
+    expect(data.status).toBe(200)
+
+    // Listing exposes metadata only — never the token.
+    const listed = await app.request(base, { headers: { cookie } })
+    expect(listed.status).toBe(200)
+    const list = await TestApp.json(listed, Keys.schema.listApiKeys.Response)
+    expect(list.data.map(({ id }) => id)).toEqual([created.id])
+    expect(JSON.stringify(list)).not.toContain(created.token)
+    expect(list.data[0]!.tokenLast4).toBe(created.token.slice(-4))
+
+    const revoked = await app.request(`${base}/${created.id}`, {
+      headers: { cookie },
+      method: 'DELETE',
+    })
+    expect(revoked.status).toBe(200)
+    expect(await TestApp.json(revoked, Keys.schema.revokeApiKey.Response)).toEqual({
+      id: created.id,
+    })
+
+    // With the resolve cache disabled, revocation is immediate.
+    const after = await app.request('/v1/tokens', {
+      headers: { 'cache-control': 'no-store', 'tempo-api-key': created.token },
+    })
+    expect(after.status).toBe(401)
+    const empty = await TestApp.json(
+      await app.request(base, { headers: { cookie } }),
+      Keys.schema.listApiKeys.Response,
+    )
+    expect(empty).toEqual({ data: [] })
+  })
+
+  test('rejects the wildcard scope at mint', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+
+    const response = await app.request(
+      `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+      json('POST', cookie, { scopes: ['*'] }),
+    )
+    expect(response.status).toBe(400)
+  })
+
+  test('rejects session mints while no scope is self-issuable', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+
+    const response = await app.request(
+      `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+      json('POST', cookie, { scopes: ['data:read'] }),
+    )
+    expect(response.status).toBe(403)
+    const { requestId, ...body } = (await response.json()) as { requestId?: string }
+    expect(requestId).toBeDefined()
+    expect(body).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "scope_not_issuable",
+          "message": "The requested scopes are not issuable.",
+        },
+      }
+    `)
+  })
+
+  test('binds keys to their project on every verb', async () => {
+    const app = createApp()
+    const owner = await session(app)
+    const { org, project } = await fixture(app, owner)
+    const other = await TestApp.json(
+      await app.request(`/v1/orgs/${org.id}/projects`, json('POST', owner, { name: 'Payments' })),
+      Projects.schema.Project,
+    )
+    const minted = await TestApp.json(
+      await app.request(
+        `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+        superAdminJson('POST', { scopes: ['data:read'] }),
+      ),
+      Keys.schema.createApiKey.Response,
+    )
+
+    // Same org, sibling project: the key id must not resolve through it.
+    const crossList = await app.request(`/v1/orgs/${org.id}/projects/${other.id}/api-keys`, {
+      headers: { cookie: owner },
+    })
+    expect((await TestApp.json(crossList, Keys.schema.listApiKeys.Response)).data).toEqual([])
+    const crossRevoke = await app.request(
+      `/v1/orgs/${org.id}/projects/${other.id}/api-keys/${minted.id}`,
+      { headers: { cookie: owner }, method: 'DELETE' },
+    )
+    expect(crossRevoke.status).toBe(404)
+
+    // Foreign session: the whole surface 404s at the org-ownership link.
+    const stranger = await session(app)
+    const foreignMint = await app.request(
+      `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+      json('POST', stranger, { scopes: ['data:read'] }),
+    )
+    expect(foreignMint.status).toBe(404)
+    const foreignRevoke = await app.request(
+      `/v1/orgs/${org.id}/projects/${project.id}/api-keys/${minted.id}`,
+      { headers: { cookie: stranger }, method: 'DELETE' },
+    )
+    expect(foreignRevoke.status).toBe(404)
+
+    // The key survives every attempt, still listed for the owner.
+    const listed = await app.request(`/v1/orgs/${org.id}/projects/${project.id}/api-keys`, {
+      headers: { cookie: owner },
+    })
+    const list = await TestApp.json(listed, Keys.schema.listApiKeys.Response)
+    expect(list.data.map(({ id }) => id)).toEqual([minted.id])
+  })
+
+  test('revokes keys when their project or organization is deleted', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+    const minted = await TestApp.json(
+      await app.request(
+        `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+        superAdminJson('POST', { scopes: ['data:read'] }),
+      ),
+      Keys.schema.createApiKey.Response,
+    )
+
+    const deletedProject = await app.request(`/v1/orgs/${org.id}/projects/${project.id}`, {
+      headers: { cookie },
+      method: 'DELETE',
+    })
+    expect(deletedProject.status).toBe(200)
+    const afterProject = await app.request('/v1/tokens', {
+      headers: { 'cache-control': 'no-store', 'tempo-api-key': minted.token },
+    })
+    expect(afterProject.status).toBe(401)
+
+    // Org deletion revokes keys of every remaining project.
+    const other = await TestApp.json(
+      await app.request(`/v1/orgs/${org.id}/projects`, json('POST', cookie, { name: 'Payments' })),
+      Projects.schema.Project,
+    )
+    const survivor = await TestApp.json(
+      await app.request(
+        `/v1/orgs/${org.id}/projects/${other.id}/api-keys`,
+        superAdminJson('POST', { scopes: ['data:read'] }),
+      ),
+      Keys.schema.createApiKey.Response,
+    )
+    const deletedOrg = await app.request(`/v1/orgs/${org.id}`, {
+      headers: { cookie },
+      method: 'DELETE',
+    })
+    expect(deletedOrg.status).toBe(200)
+    const afterOrg = await app.request('/v1/tokens', {
+      headers: { 'cache-control': 'no-store', 'tempo-api-key': survivor.token },
+    })
+    expect(afterOrg.status).toBe(401)
+  })
+
+  test('keeps the project when key revocation fails during project deletion', async () => {
+    const store = TestApp.kvStore({ keys: [] })
+    const app = createApp({ kv: { store } })
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+    await TestApp.json(
+      await app.request(
+        `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+        superAdminJson('POST', { scopes: ['data:read'] }),
+      ),
+      Keys.schema.createApiKey.Response,
+    )
+    failRecordDeletes(store)
+
+    const deletedProject = await app.request(`/v1/orgs/${org.id}/projects/${project.id}`, {
+      headers: { cookie },
+      method: 'DELETE',
+    })
+    expect(deletedProject.status).toBe(502)
+
+    const projectStill = await app.request(`/v1/orgs/${org.id}/projects/${project.id}`, {
+      headers: { cookie },
+    })
+    expect(projectStill.status).toBe(200)
+  })
+
+  test('keeps the organization when key revocation fails during organization deletion', async () => {
+    const store = TestApp.kvStore({ keys: [] })
+    const app = createApp({ kv: { store } })
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+    await TestApp.json(
+      await app.request(
+        `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+        superAdminJson('POST', { scopes: ['data:read'] }),
+      ),
+      Keys.schema.createApiKey.Response,
+    )
+    failRecordDeletes(store)
+
+    const deletedOrg = await app.request(`/v1/orgs/${org.id}`, {
+      headers: { cookie },
+      method: 'DELETE',
+    })
+    expect(deletedOrg.status).toBe(502)
+
+    const orgStill = await app.request(`/v1/orgs/${org.id}`, { headers: { cookie } })
+    expect(orgStill.status).toBe(200)
+  })
+
+  test('mints as the super admin with super admin attribution', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+
+    const minted = await app.request(`/v1/orgs/${org.id}/projects/${project.id}/api-keys`, {
+      body: JSON.stringify({ scopes: ['data:read'] }),
+      headers: { 'content-type': 'application/json', 'tempo-api-key': secret },
+      method: 'POST',
+    })
+    expect(minted.status).toBe(200)
+    const created = await TestApp.json(minted, Keys.schema.createApiKey.Response)
+    expect(created.createdBy).toBe('super_admin')
+    expect(created.environment).toBe('production')
+  })
+
+  test('rejects API keys on the keys surface', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+
+    const response = await app.request(`/v1/orgs/${org.id}/projects/${project.id}/api-keys`, {
+      headers: { 'tempo-api-key': TestApp.key.token },
+    })
+    expect(response.status).toBe(403)
+  })
+})