FEDEO/skills/openclaw-m2m-openapi/SKILL.md

name, description

name	description
openclaw-m2m-openapi	Implement and maintain OpenAPI plus machine-to-machine access for FEDEO/OpenClaw-style Fastify backends. Use when creating tenant-bound API keys, authenticating M2M callers, exchanging API keys for short-lived JWTs, exposing OpenAPI docs/spec endpoints, and ensuring req.user is populated for impersonated tenant/user execution.

OpenClaw M2M + OpenAPI

Implement OpenAPI publication and M2M authentication with tenant+user impersonation.

Define Data Model

Create a DB table for M2M API keys with at least:

• Key identity: id, name, key_prefix, key_hash
• Scope: tenant_id, user_id
• Lifecycle: active, expires_at, last_used_at, created_at, updated_at
• Auditing: created_by

Store only a hash (sha256) of the key, never plaintext.

Publish OpenAPI

Configure Fastify Swagger dynamically and expose:

• UI endpoint: /docs
• Raw spec endpoint: /openapi.json

Define OpenAPI metadata and bearer auth security schema (bearerAuth).

Implement M2M Authentication

In M2M auth plugin:

1. Read API key from x-api-key.
2. Hash and compare against key_hash in DB.
3. Reject missing/invalid/inactive/expired keys with 401.
4. Load mapped tenant/user.
5. Populate req.user with:
   • user_id
   • email
   • tenant_id
6. Update key usage metadata (last_used_at, updated_at).

Always keep req.user compatible with existing JWT-authenticated route expectations.

Implement API Key Management

Expose tenant-scoped management endpoints on authenticated API routes:

• GET /api/tenant/api-keys
• POST /api/tenant/api-keys
• PATCH /api/tenant/api-keys/:id
• DELETE /api/tenant/api-keys/:id

For create:

• Generate random plaintext key once.
• Return plaintext only in create response.
• Persist only hash + prefix.
• Enforce that selected user_id belongs to current tenant.

Add Token Exchange (Preferred M2M Flow)

Expose internal route:

• POST /internal/auth/m2m/token

Behavior:

1. Require M2M-authenticated request.
2. Revalidate tenant membership of impersonated user.
3. Issue short-lived JWT signed with app JWT secret.
4. JWT payload must include user_id, email, tenant_id.

Use this JWT for normal /api/* requests via Authorization: Bearer <token>.

Security Rules

• Never log full API keys.
• Enforce TTL bounds for exchanged JWTs (e.g. 60..3600 seconds).
• Treat expired keys as unauthorized.
• Keep key hash comparison deterministic and normalized.
• Keep management endpoints tenant-isolated.

Verification Checklist

Run and verify:

1. Backend build passes.
2. OpenAPI UI and raw spec are reachable.
3. API key create/list/update/delete works per tenant.
4. Exchange endpoint returns JWT.
5. JWT can call /api/me and shows impersonated tenant/user.

Quick Commands

# Build backend
npm run build

# Exchange key for JWT
curl -X POST http://localhost:3000/internal/auth/m2m/token \
  -H "x-api-key: <M2M_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"expires_in_seconds":900}'

# Use exchanged JWT on normal API
curl http://localhost:3000/api/me \
  -H "Authorization: Bearer <ACCESS_TOKEN>"