app-identity-dev-enroll

Files (1)

• SKILL.md

SKILL.md (first lines)

# App Identity dev enrollment

Bring a fresh developer (or a fresh machine for an existing developer) to
the state where `folddb-dev app publish` + `folddb-dev schema publish
--app <id>` work. The output is a populated `~/.folddb-dev/developer/`
keypair + a row in `ExememDevelopers-{env}` + (dev only) an
`EXEMEM_DEV_API_KEY` minted into the API-keys DynamoDB table.

This is the "Step 1 + 2a/2b" subset of the larger `app-identity-dogfood`
flow, factored out for reuse: any app developer (brain, kanban, future
third-party) onboards through this skill, then runs the publish steps for
their own app.

Authoritative spec: `~/code/edgevector/exemem-workspace/docs/designs/app_identity.md`
(v3.1). Sections: *Developer enrollment & cert minting*, *Two keys, one
consent-token model*.

## 🛑 Hard safety rules (read first)

1. **Prod row writes are admin-gated by design.** The skill refuses to put
   a row into `ExememDevelopers-prod` no matter how it's invoked — if the
   target env is prod, the skill prints the exact `aws dynamodb put-item`
   command for a human admin to run and stops. The prod *API key* mint is
   also refused (same reason — prod keys are issued via the portal +
   billing flow, not by an autonomous skill).
2. **Idempotent re-runs.** Existing rows are not overwritten; existing
   keypairs are not rotated. If the developer keypair already exists, the
   skill reuses it. If the developer is already enrolled, the skill is a
   no-op. Pass `--rotate-key` to opt into key rotation (NOT default —
   rotating invalidates every DevCert minted from the old key).
3. **Never run `folddb-dev developer init --force`** unless the user
   explicitly asks. `--force` rotates the keypair, the old one stops
   minting DevCerts, and every published-app row that names the old
   `owner_dev_pubkey` becomes orphaned (those apps can no longer be
   re-published or have their schemas extended by this machine).
4. **Don't touch the primary LastDB brain (the legacy `folddb_server` binary name may appear)** — this skill writes
   to DynamoDB and runs `folddb-dev` CLI verbs; it does NOT start a dev
   session and does NOT need the homebrew daemon.

## Inputs

Resolved from arguments / env / sensible defaults, in order:

| Variable | Default | How resolved |
|---|---|---|
| `ENV`        | `dev` | First positional arg or `--env`. Accepts `dev` or `prod`. |
| `USER_HASH`  | required | Second positional arg or `--user-hash`. Must be a stable identifier for this developer (e.g. `REPLACE-brain-dev`, `kanban-rust-dev`). Ask if not provided. |
| `HANDLE`     | `$USER_HASH` | `--handle`. Cosmetic; recorded in the local keypair file alongside the key, never sent on the wire. |

If `USER_HASH` is ambiguous (no arg + ambiguous from the prompt), ASK the
user — don't pick one. Re-running with a different `USER_HASH` is fine
(it provisions a separate enrollment) but wastes a DDB row.

## Tables (canonical names)

Match these EXACTLY — the CDK uses generated names with random suffixes.

| Env  | Region    | API-keys table                                       | Developers table        |
|------|-----------|------------------------------------------------------|-------------------------|
| dev  | us-west-2 | `ExememStack-dev-ApiKeysTable9F4DC7E7-ECJE82X9TR56`  | `ExememDevelopers-dev`  |
| prod | us-east-1 | (find via `aws dynamodb list-tables` — name carries a different CDK suffix) | `ExememDevelopers-prod` |

If a table name above is stale (the CDK was redeployed and the suffix
changed), find the current name via
`aws dynamodb list-tables --region us-west-2 --query "TableNames[?contains(@, \`ApiKeys\`)]"`
and update the skill — don't silently fall back to a guess.

## Step 1 — guard prod (refuses + emits runbook)

```bash
if [ "$ENV" = "prod" ]; then
  cat <<'EOF'
PROD ENROLLMENT IS ADMIN-GATED — this skill refuses to write production
rows. Send the following two commands to a human Exemem admin (or run
them yourself with admin credentials):

  # 1. Mint an EXEMEM_DEV_API_KEY (issued via portal/Stripe in steady
  #    state; this is the dev-only bypass shape).
  REGION=us-east-1
  API_TBL=$(aws dynamodb list-tables --region "$REGION" \
    --query "TableNames[?contains(@, 'ApiKeys')]" --output text)
  USER_HASH=<the developer's identifier>
  NOW_EPOCH=$(date -u +%s)
  API_KEY="em_$(LC_ALL=C tr -dc 'a-f0-9' </dev/urandom | head -c48)"
  KEY_HASH=$(printf '%s' "$API_KEY" | shasum -a 256 | cut -d' ' -f1)
  aws dynamodb put-item --region "$REGION" --table-name "$API_TBL" \
    --item "{\"api_key_hash\":{\"S\":\"$KEY_HASH\"},\"user_hash\":{\"S\":\"$USER_HASH\"},\"created_at\":{\"N\":\"$NOW_EPOCH\"},\"is_active\":{\"BOOL\":true},\"label\":{\"S\":\"app-identity-dev-enroll prod\"}}"
  echo "API_KEY=$API_KEY  (send securely to the developer)"

  # 2. Enroll the developer's local pubkey (the developer first runs
  #    `folddb-dev developer init` on their machine and ships you the
  #    base64 pubkey).
  DEV_PUBKEY=<base64 ed25519 pubkey from the developer>
  NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
  # developer_access=true is the publish gate (fold PR #444): without it the
  # cert mints but schema_service 403s not_authorized_publisher. (In prod a
  # paid billing plan also satisfies the gate; the explicit grant is the
  # invite/admin path.)
  aws dynamodb put-item --region "$REGION" --table-name ExememDevelopers-prod \
    --item "{\"user_hash\":{\"S\":\"$USER_HASH\"},\"dev_pubkey\":{\"S\":\"$DEV_PUBKEY\"},\"status\":{\"S\":\"active\"},\"developer_access\":{\"BOOL\":true},\"enrolled_at\":{\"S\":\"$NOW\"},\"enrolled_by\":{\"S\":\"<admin user_hash>\"}}"
EOF
  exit 0
fi
```

## Step 2 — mint EXEMEM_DEV_API_KEY (dev only)

```bash
REGION=us-west-2
API_TBL=ExememStack-dev-ApiKeysTable9F4DC7E7-ECJE82X9TR56
NOW_EPOCH=$(date -u +%s)

# Idempotency check: if a row with label "app-identity-dev-enroll" already
# exists for this USER_HASH, reuse it instead of minting a new key. This
# avoids leaving orphan keys in DynamoDB across re-runs.
existing=$(aws dynamodb query --region "$REGION" --table-name "$API_TBL" \
  --index-name user_hash_index \
  --key-condition-expression "user_hash = :u" \
  --expression-attribute-values "{\":u\":{\"S\":\"$USER_HASH\"}}" \

From EdgeVector/last-stack, MIT.

More from EdgeVector/last-stack