feat(ourmoji): admin daily ingest endpoint for home-server agent

InfantLab · claude · InfantLab · commit 368cefee0b35 · 2026-04-21T10:32:47.000Z
Adds POST /api/v1/admin/ourmoji/daily — an admin-scoped endpoint that lets a trusted external agent post the daily Ourmoji oracle on behalf of any user, authenticated with a single Bearer API key (admin:users:write). Widens the key-mint schema to accept admin permissions, gated by isAdmin() so only admins can grant them.

Ships a walkthrough at docs/modules/ourmoji-agent-setup.md covering key minting, per-user module enablement, daily POST shape, and key rotation — all with full production URLs.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/app/server/api/ourmoji/schemas.ts b/app/server/api/ourmoji/schemas.ts
@@ -35,6 +35,20 @@ export const dailyOurmojiPayloadSchema = z.object({
 
 export type DailyOurmojiPayload = z.infer<typeof dailyOurmojiPayloadSchema>;
 
+/**
+ * Admin variant — same fields as `dailyOurmojiPayloadSchema` plus a
+ * target `userId` so a privileged caller can post on behalf of any
+ * user. Used by `POST /api/v1/admin/ourmoji/daily`.
+ */
+export const adminDailyOurmojiPayloadSchema =
+  dailyOurmojiPayloadSchema.extend({
+    userId: z.string().min(1),
+  });
+
+export type AdminDailyOurmojiPayload = z.infer<
+  typeof adminDailyOurmojiPayloadSchema
+>;
+
 export const calendarQuerySchema = z.object({
   from: isoDate.optional(),
   to: isoDate.optional(),
diff --git a/app/server/api/v1/admin/ourmoji/daily.post.ts b/app/server/api/v1/admin/ourmoji/daily.post.ts
@@ -0,0 +1,101 @@
+/**
+ * POST /api/v1/admin/ourmoji/daily
+ *
+ * Admin ingestion endpoint — posts a single day's Ourmoji payload on
+ * behalf of a target user. Intended for trusted server-to-server agents
+ * (e.g. the home-server oracle) authenticated with an admin API key.
+ *
+ * Auth: requires admin + `admin:users:write` permission (API keys).
+ * Sessions held by an admin also work.
+ *
+ * Idempotent per (userId, date): a re-post for the same date updates
+ * the existing entry rather than duplicating.
+ */
+
+import { defineEventHandler, readBody, createError } from "h3";
+
+import { requireAdmin } from "~/server/utils/admin";
+import {
+  notFound,
+  success,
+  validationError,
+} from "~/server/utils/response";
+import { logAuthEvent } from "~/server/utils/authEvents";
+import { db } from "~/server/db";
+import { users } from "~/server/db/schema";
+import { eq } from "drizzle-orm";
+
+import { isOurmojiEnabledForUser } from "~/server/services/ourmoji/access";
+import { upsertDailyOurmoji } from "~/server/services/ourmoji/daily";
+import { ourmojiApiLogger as logger } from "~/server/services/ourmoji/logger";
+import { adminDailyOurmojiPayloadSchema } from "~/server/api/ourmoji/schemas";
+
+export default defineEventHandler(async (event) => {
+  requireAdmin(event, "admin:users:write");
+
+  const body = await readBody(event);
+  const parsed = adminDailyOurmojiPayloadSchema.safeParse(body);
+
+  if (!parsed.success) {
+    const errors: Record<string, string[]> = {};
+    for (const issue of parsed.error.issues) {
+      const path = issue.path.join(".") || "_root";
+      if (!errors[path]) errors[path] = [];
+      errors[path].push(issue.message);
+    }
+    throw createError(validationError(event, errors));
+  }
+
+  const payload = parsed.data;
+
+  const targetUser = await db
+    .select({ id: users.id })
+    .from(users)
+    .where(eq(users.id, payload.userId))
+    .limit(1);
+
+  if (targetUser.length === 0) {
+    throw createError(notFound(event, "User"));
+  }
+
+  const enabled = await isOurmojiEnabledForUser(payload.userId);
+  if (!enabled) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Target user does not have the ourmoji module enabled",
+    });
+  }
+
+  const dto = await upsertDailyOurmoji({
+    userId: payload.userId,
+    date: payload.date,
+    emoji: payload.emoji,
+    reflection: payload.reflection,
+    moonPhase: payload.moonPhase,
+    moonIllumination: payload.moonIllumination ?? null,
+    wheelOfYear: payload.wheelOfYear ?? null,
+    wheelCategory: payload.wheelCategory ?? null,
+    timezone: payload.timezone,
+    source: "api",
+  });
+
+  const auth = event.context.auth!;
+  await logAuthEvent({
+    event,
+    userId: auth.userId,
+    eventType: "admin:user_updated",
+    metadata: {
+      targetUserId: payload.userId,
+      action: "ourmoji_daily_ingested",
+      date: payload.date,
+    },
+  });
+
+  logger.info("Admin ingested Ourmoji daily", {
+    adminUserId: auth.userId,
+    targetUserId: payload.userId,
+    date: payload.date,
+  });
+
+  return success(event, { entry: dto });
+});
diff --git a/app/server/api/v1/auth/keys.post.ts b/app/server/api/v1/auth/keys.post.ts
@@ -7,13 +7,23 @@
  */
 
 import * as z from "zod";
-import { created, apiError, validationError } from "~/server/utils/response";
+import { created, apiError, validationError, forbidden } from "~/server/utils/response";
 import { createApiKey } from "~/server/utils/api-key";
 import { createLogger } from "~/server/utils/logger";
+import { isAdmin } from "~/server/utils/admin";
 import type { Permission } from "~/types/api";
 
 const logger = createLogger("api:v1:auth:keys:create");
 
+const ADMIN_PERMISSIONS = [
+  "admin:stats",
+  "admin:users",
+  "admin:users:write",
+  "admin:activity",
+  "admin:health",
+  "admin:feedback",
+] as const satisfies readonly Permission[];
+
 // Validation schema for API key creation
 const createKeySchema = z.object({
   name: z.string().min(1).max(100),
@@ -26,7 +36,9 @@ const createKeySchema = z.object({
         "insights:read",
         "export:read",
         "webhooks:manage",
+        "sync:manage",
         "user:read",
+        ...ADMIN_PERMISSIONS,
       ]),
     )
     .min(1)
@@ -71,6 +83,15 @@ export default defineEventHandler(async (event) => {
 
   const { name, permissions, expiresAt } = parseResult.data;
 
+  const requestsAdminPerm = permissions.some((p) =>
+    (ADMIN_PERMISSIONS as readonly string[]).includes(p),
+  );
+  if (requestsAdminPerm && !isAdmin(userId)) {
+    throw createError(
+      forbidden(event, "Admin permissions can only be granted to admin users"),
+    );
+  }
+
   try {
     // Create new API key
     const result = await createApiKey(
diff --git a/docs/modules/ourmoji-agent-setup.md b/docs/modules/ourmoji-agent-setup.md
@@ -0,0 +1,211 @@
+# Ourmoji — Home-Server Agent Setup
+
+How to configure an external agent (running on your home server) to post the
+daily Ourmoji oracle on behalf of multiple users.
+
+The agent authenticates as the project owner using a single long-lived API key
+with admin scope, and posts to an admin-only endpoint that accepts a target
+`userId`. No per-user session cookies or per-user keys are needed.
+
+Production base URL: `https://tada.living`
+
+Replace `https://tada.living` below if running against a different deployment
+(e.g. `http://localhost:3000` for local dev).
+
+---
+
+## Prerequisites
+
+1. **You are an admin.** Your user id must be listed in the server-side
+   `ADMIN_USER_IDS` env var (comma-separated).
+2. **You know both user ids** — Caspar's (yours) and Marian's.
+   You can find user ids via `GET https://tada.living/api/v1/admin/users` once
+   you have a session, or in the database directly.
+3. **You are logged in to tada in a browser** on the same origin (for the key
+   minting step, which requires session auth).
+
+---
+
+## Step 1 — Mint the API key (browser)
+
+Open the devtools console on any `https://tada.living/*` page while signed in,
+and run:
+
+```js
+await fetch("https://tada.living/api/v1/auth/keys", {
+  method: "POST",
+  credentials: "include",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    name: "home-server ourmoji agent",
+    permissions: ["admin:users:write"],
+  }),
+}).then((r) => r.json());
+```
+
+The response includes a `key` field of the form `tada_key_…`. **This is the
+only time the plaintext key is ever shown.** Copy it to the home-server agent's
+secret store immediately. If you lose it, revoke and mint a new one.
+
+> `admin:users:write` is the same permission used by the existing admin
+> module-toggle and user-update endpoints. A single key with this scope can
+> post daily Ourmoji for any user, toggle feature flags, update users, reset
+> passwords, clear sessions, etc. Treat it like a root credential — do not
+> share it outside the home-server agent.
+
+---
+
+## Step 2 — Enable Ourmoji for each user (one-shot)
+
+The agent can only post for users who have the `ourmoji` module flag turned
+on. Do this once per user from the home server (or anywhere with curl):
+
+**For Caspar (you):**
+
+```bash
+curl -X PATCH https://tada.living/api/v1/admin/users/<CASPAR_USER_ID>/modules \
+  -H "Authorization: Bearer tada_key_…" \
+  -H "Content-Type: application/json" \
+  -d '{"ourmoji": true}'
+```
+
+**For Marian:**
+
+```bash
+curl -X PATCH https://tada.living/api/v1/admin/users/<MARIAN_USER_ID>/modules \
+  -H "Authorization: Bearer tada_key_…" \
+  -H "Content-Type: application/json" \
+  -d '{"ourmoji": true}'
+```
+
+A 200 with `{"data": {"enabledModules": {"ourmoji": true, …}}}` confirms the
+flag is set.
+
+---
+
+## Step 3 — Verify the key (optional)
+
+Quick sanity check from the home server:
+
+```bash
+curl https://tada.living/api/v1/admin/health \
+  -H "Authorization: Bearer tada_key_…"
+```
+
+Expect a 200. If you get 401, the key is wrong or revoked. If you get 403,
+your user is not in `ADMIN_USER_IDS` on the server.
+
+---
+
+## Step 4 — Daily posting (what the agent does each morning)
+
+Once per user per day, POST to `/api/v1/admin/ourmoji/daily`:
+
+```bash
+curl -X POST https://tada.living/api/v1/admin/ourmoji/daily \
+  -H "Authorization: Bearer tada_key_…" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "userId": "<CASPAR_USER_ID>",
+    "date": "2026-04-21",
+    "emoji": "🌙",
+    "reflection": "The waning gibbous whispers of release.",
+    "moonPhase": "Waning Gibbous",
+    "moonIllumination": 75,
+    "wheelOfYear": "Beltane",
+    "wheelCategory": "fire",
+    "timezone": "Europe/London"
+  }'
+```
+
+### Field reference
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `userId` | string | yes | Target user (Caspar or Marian) |
+| `date` | string `YYYY-MM-DD` | yes | Local date the entry belongs to |
+| `emoji` | string (1–16 chars) | yes | Drawn from the 23-emoji Sacred Set |
+| `reflection` | string (≤ 5000 chars) | yes | Poetic reflection text |
+| `moonPhase` | string | yes | e.g. "Waning Gibbous" |
+| `moonIllumination` | number 0–100 | no | Percent illuminated |
+| `wheelOfYear` | string | no | e.g. "Beltane", "Samhain" |
+| `wheelCategory` | string | no | e.g. "fire", "water" |
+| `timezone` | string | yes | IANA zone, e.g. "Europe/London" |
+
+### Idempotency
+
+The endpoint is idempotent per `(userId, date)` — re-posting for the same date
+updates the existing entry rather than creating a duplicate. Safe to retry on
+network failure.
+
+### Response
+
+```json
+{
+  "data": {
+    "entry": {
+      "id": "…",
+      "date": "2026-04-21",
+      "emoji": "🌙",
+      "reflection": "…",
+      "moonPhase": "Waning Gibbous",
+      "moonIllumination": 75,
+      "wheelOfYear": "Beltane",
+      "wheelCategory": "fire",
+      "timestamp": "2026-04-21T00:00:00Z",
+      "timezone": "Europe/London"
+    }
+  }
+}
+```
+
+### Error cases
+
+| Status | Meaning | Fix |
+|--------|---------|-----|
+| 400 | "Target user does not have the ourmoji module enabled" | Run Step 2 for that user |
+| 401 | Missing/invalid Bearer token | Check the key |
+| 403 | Admin check failed | Ensure your user id is in `ADMIN_USER_IDS` |
+| 404 | Target user does not exist | Check the `userId` value |
+| 422 | Validation error | Check the payload shape against the table above |
+
+---
+
+## Rotating / revoking the key
+
+List your keys (browser console, logged in):
+
+```js
+await fetch("https://tada.living/api/v1/auth/keys", {
+  credentials: "include",
+}).then((r) => r.json());
+```
+
+Revoke by id:
+
+```js
+await fetch("https://tada.living/api/v1/auth/keys/<KEY_ID>", {
+  method: "DELETE",
+  credentials: "include",
+});
+```
+
+Then redo Step 1 to mint a replacement and swap it into the agent's secret
+store.
+
+---
+
+## What the agent needs to hold
+
+- Base URL (`https://tada.living`)
+- One Bearer token (`tada_key_…`)
+- Caspar's user id
+- Marian's user id
+- Whatever it uses to compute each day's emoji / moon / Wheel of Year / reflection
+
+That's it — no session cookies, no per-user credentials, no rotation
+co-ordination across users.
+
+---
+
+[Back to Ourmoji](./ourmoji.md)
diff --git a/docs/modules/ourmoji.md b/docs/modules/ourmoji.md
@@ -76,6 +76,10 @@ Requires admin auth (`ADMIN_USER_IDS` env var) with `admin:users:write` permissi
 
 Full design lives in [`specs/013-ourmoji-module/`](../../specs/013-ourmoji-module/) — see `spec.md`, `data-model.md`, and `contracts/openapi.yaml`.
 
+## Related docs
+
+- [Home-server agent setup](./ourmoji-agent-setup.md) — configuring an external agent to post the daily Ourmoji on behalf of multiple users
+
 ---
 
 [Back to modules](./README.md)
