Skip to content

ahstn/oceans-llm / .agents/skills/verify-oceans-admin

verify-oceans-admin

Verified

Verify the Oceans LLM admin control plane and backend gateway against the real local stack, seeded demo data, and bounded live providers when required. Use for user-path checks of sign-in, models, API keys, observability, usage costs, spend controls, batches, agent sessions, request logs, Anthropic Messages thinking and effort compatibility, MCP registry and tool access, OpenRouter routing, guardrails, and Skills storage.

FileKindSize
SKILL.mdskill md29.0 KB
examples/mcp-candidates.jsonconfig3.0 KB
features/README.mdmarkdown10.0 KB
features/account-onboarding.mdmarkdown4.3 KB
features/agent-harnesses.mdmarkdown4.3 KB
features/agent-plugins.mdmarkdown1005 B
features/agent-sessions.mdmarkdown3.9 KB
features/anthropic-messages.mdmarkdown20.7 KB
features/api-keys.mdmarkdown6.5 KB
features/attribution.mdmarkdown13.9 KB
features/audit-log.mdmarkdown4.9 KB
features/backend-gateway.mdmarkdown5.2 KB
features/batch-requests.mdmarkdown4.2 KB
features/design-system.mdmarkdown4.6 KB
features/guardrails.mdmarkdown7.0 KB
features/harness-integration.mdmarkdown7.8 KB
features/identity.mdmarkdown4.2 KB
features/image-generation.mdmarkdown7.3 KB
features/leaderboard.mdmarkdown3.3 KB
features/live-llm-requests.mdmarkdown12.6 KB
features/mcp-client-oauth.mdmarkdown9.9 KB
features/mcp-ownership.mdmarkdown7.4 KB
features/mcp.mdmarkdown19.6 KB
features/models.mdmarkdown8.2 KB
features/password-sign-in.mdmarkdown8.3 KB
features/profile.mdmarkdown2.5 KB
features/rate-limits.mdmarkdown6.0 KB
features/request-logs.mdmarkdown8.6 KB
features/review-agent.mdmarkdown3.7 KB
features/routing.jsonconfig33.6 KB
features/service-tiers.mdmarkdown6.3 KB
features/skills.mdmarkdown9.8 KB
features/spend-controls.mdmarkdown7.3 KB
features/usage-costs.mdmarkdown3.7 KB
features/workspace-connections.mdmarkdown6.1 KB
scripts/check-messages.mjsexecutablescript2.4 KB
scripts/check-messages.test.mjsscript3.0 KB
scripts/control-oceans-adminexecutablescript25.3 KB
scripts/control-oceans-admin.test.mjsscript7.6 KB
scripts/drive-backend-gateway.mjsexecutablescript12.5 KB
scripts/drive-harness-integration.mjsscript6.6 KB
scripts/drive-mcp.mjsscript13.0 KB
scripts/drive-models.mjsscript12.9 KB
scripts/drive-observability.mjsscript16.8 KB
scripts/drive-profile.mjsscript8.2 KB
scripts/drive-service-tiers.mjsexecutablescript20.1 KB
scripts/drive-skills.mjsscript27.2 KB
scripts/mcp-browser.mjsscript26.5 KB
scripts/mcp-canary.mjsscript18.8 KB
scripts/mcp-candidates.mjsscript3.5 KB
scripts/mcp-verification.test.mjsscript10.2 KB
scripts/messages-regressions.mjsscript15.8 KB
scripts/plan-verification.mjsscript5.2 KB
scripts/plan-verification.test.mjsscript6.1 KB
scripts/proof-cli.mjsscript11.1 KB
scripts/proof.mjsscript9.2 KB
scripts/proof.test.mjsscript10.4 KB

features/api-keys.md

View on GitHub
# API keys

API Keys lets an authorized user review keys in scope, create a key for an owner allowed by their role, change model access for user-owned keys, limit a key to capability scopes and MCP servers, and revoke a key. A newly created key exposes its raw secret in the creation result. An authorized team or platform administrator can reveal an active service-account-owned key later.

## Sub-features

- `keys-list` shows API keys allowed by the current user's scope.
- `keys-create` creates a named key for an owner allowed by the signed-in user's role.
- `keys-secret-once` shows every newly created raw key in the creation result; user-owned keys cannot be revealed again.
- `keys-manage` opens effective model access and, for an authorized active service-account key, later reveal controls. Service-account keys are locked to `Selected models`, but their `Granted models` list stays editable through `Save access`.
- `keys-scopes` limits a key to capability scopes (`inference`, `mcp:aggregate`, `mcp:proxy`) and, with an MCP scope, to selected MCP servers. Set on create or later in `Manage API key`; saved through `PUT /api/v1/admin/api-keys/{api_key_id}/scopes`. See [ADR: scoped API keys](../../../../docs/adr/2026-10-17-scoped-api-keys.md).
- `keys-revoke` revokes a key and prevents later gateway use.

## How to get to it (user POV)

- Sign in and choose `API Keys` under `Control Plane`.
- Open `/admin/api-keys`; an unauthenticated user is sent to sign-in first.
- Use `Create API key` for a new key or `Manage` in a key row for an existing key.
- Open `/admin/api-keys?api_key_id=<id>` to land directly in `Manage API key`.

## Driving it with control-oceans-admin

Preconditions:

- `control-oceans-admin doctor` passes.
- Sign in as a user whose action permissions include the operation under test.
- Use a unique key name that contains the verification run ID.

- **List.** Choose `API Keys`. The `API keys` heading and the `Keys` card appear for the current scope.
- **Open create.** Choose `Create API key`. A creation dialog appears with `Name`, `Owner type`, owner selection, and model access controls.
- **Model grant selector.** In both create and manage dialogs, `All models` and `Selected models` use separate bordered pills, with a lilac selected state matching the Models client config selector. Switching modes shows or hides `Granted models`; clicking the selected pill keeps it selected. Service-account mode stays disabled.
- **Create.** Fill `Name`, choose an allowed owner, set model access, and choose the final `Create API key` button. The toast reads `API key created`, and the `Copy the new key now` alert's `new-api-key-raw-key` element holds a raw key starting with `gwk_`. Use it in memory only, then choose `Dismiss` before any screenshot.
- **Confirm use.** Call `/v1/models` with the new key and confirm that returned model IDs equal the effective intersection of the selected grants and owner/model allowlists. Do not store the raw key in proof.
- **Scopes on create.** In the create dialog, set the `Capabilities` toggle to `Limited` and tick `MCP proxy` (`create-api-key-scope-mcp:proxy`). The `MCP servers` toggle appears; choose `Selected servers` and tick one seeded server. `Create API key` stays disabled until at least one scope, and at least one server under `Selected servers`, is ticked. The new row's `Scopes` column reads `MCP proxy · <server_key>`.
- **Scope refusal.** With that key, `GET /v1/models` returns `403` with `error.code` `insufficient_scope`. `POST /mcp/<listed server>` with `tools/list` passes the scope check. `POST /mcp/<other server>` returns `403` with a JSON-RPC error (`error.code` `-32001`, `error.data.error` `insufficient_scope`).
- **Edit scopes.** In `Manage API key`, set `Capabilities` back to `Full access` and choose `Save access`. The toast reads `API key updated`, the row's `Scopes` column reads `Full access`, `GET /v1/models` with the same key now succeeds, and the audit log shows one `api_key.scopes_updated` entry with `before` and `after`.
- **Manage user key.** Locate the row by the unique name and choose `Manage`. The `Manage API key` dialog shows the masked key identity and current owner. It permits model-access changes and does not offer `Reveal API key` for a user-owned key.
- **Service-account reveal availability.** Manage the seeded active `Local CI Runner Key`. The `Model grant mode` radios are disabled, and `manage-api-key-secret` shows `Credential secret` and `Reveal API key` when the session has `reveal_api_key`. Confirm the control is present, but never click it. Choose `Cancel`.
- **Revoke and cleanup.** In `Manage API key`, under `Lifecycle actions`, choose `Revoke key`. It acts immediately, with no confirmation. The toast reads `API key revoked` and the row Status reads `revoked`. Confirm that `/v1/models` rejects the key. The created record can remain as a revoked audit record; record its name and revoked state.
- **Proof.** Capture the create form, masked created result, managed access state, and revoked list state. Redact the raw key from screenshots, traces, logs, and JSON.

## Gotchas

- The `Owner user` picker lists the seeded demo users but not the bootstrap `admin@local`. Use a seeded user such as `alice@platform.local` as the owner of a temporary key.
- This feature mutates `gateway.db`; do not run it as part of the read-only baseline.
- Every newly created raw key is shown in the creation result. User-owned keys are shown only once. Active service-account-owned keys can be revealed later by an authorized team or platform administrator. Never save either secret as an artifact.
- Revoked, user-owned, and unauthorized keys do not show the later reveal control. Revoked keys show the `Revoked keys are read-only` alert.
- The `Copy the new key now` alert says the secret cannot be revealed again, even for service-account keys that can be. For those keys, trust `Reveal API key` in Manage, not the alert copy.
- The seeded `Local CI Runner Key` stores only a hash. Revealing it fails with `api key secret is not retrievable for this key`, so check only that the control is present.
- Model access and owner options depend on the signed-in user's permissions.
- Keys without scopes, including every seeded key, show `Full access` in the `Scopes` column.
- The `MCP servers` field only appears when `Full access`, `MCP aggregate`, or `MCP proxy` is selected. Unticking the last MCP scope clears the server list.
- A scope edit and a model-access edit in one save are two requests: `PATCH` for model access, then `PUT .../scopes`. Each is audited separately.
- Revocation is the cleanup. Do not delete database files to remove one verification record.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall