---
title: Unclaimed-check capability (sign-in-gated US unclaimed-property lookup)
---

# Unclaimed-Check capability (sign-in-gated US unclaimed-property lookup)

## What it is

**Status:** in-development (gated `unclaimed-check-capability`, OFF by default). Agent-only — no UI panel.

A free, sign-in-gated capability that lets any Omniscio user's agents check whether a person is owed
**US unclaimed property** (money a state is holding) by name. It covers **California and New York**
today (more states later) and every result links to the official state site to claim for **FREE** —
never a paid finder, never government-affiliated.

The intelligence is the existing **unclaimed-check** service (a Cloud Run app over state-published
public-record data). This capability exposes it to *every signed-in Omniscio user* without shipping
the shared service key to clients: the lookup is proxied through the Omniscio **jls-gateway** using the
user's own Firebase sign-in, and the shared `x-api-key` stays server-side in Secret Manager.

## Where to find it

This has no in-app UI, and that is deliberate: it is agent-only, so no panel, sidebar row, or settings page opens it. An agent runs the lookup for you. It is also still in development, so it stays OFF until the `unclaimed-check-capability` flag is turned on.

## How it behaves

### Auth & openness

Open to **any signed-in Omniscio user** — the gateway verifies the Firebase ID token (audience +
email-verified) but does **not** require allowlist membership, because the capability is free and
rate-limited so the exposure is bounded. It is NOT a security-sensitive spend path (no credits, no
per-call money).

### Rate limits (the cost control)

It is free, so the rate limits ARE the abuse/cost control (they bound gateway egress + upstream load),
not a billing meter. Defaults (all env-tunable): **per-uid 30/min + 300/day**, **per-IP 60/min**. Each
window is an in-memory, per-instance, fail-open fixed window (a limiter fault never blocks a legit
lookup). Over a cap → `429` with `Retry-After`. Because the counters are per Cloud-Run-instance, the
effective global cap is N×max — acceptable for a free throttle (no money can be double-spent).

### Privacy

Names never store, never log. The name fields (`last`/`first`/`middle`/`city`) transit as **request
headers**, never in a URL or query string; neither the desktop route nor the gateway logs the name
headers or the request body. Name inputs are validated to reject control characters, so a crafted name
can't smuggle a header split. Only the non-PII 2-letter `state` rides the query string.

## For agents

### How it works

```
Agent → POST /unclaimed/search (127.0.0.1:19519, desktop)
  → attaches the user's Firebase ID token
  → jls-gateway POST /v1/unclaimed/search  (verifies sign-in, rate-limits, adds x-api-key)
  → unclaimed-check Cloud Run GET /search   (name in headers, state in the query)
  → JSON matches relayed back
```

- **Desktop route** (`src/main/services/cli/cli-server-unclaimed-routes.ts`): self-gates on the flag
  (404 when off), validates the body, attaches the Firebase token via `getAmcProxyToken()`, and forwards
  to `BUNDLED_API_PROXY_URL/v1/unclaimed/search`. `allowAgentSession: true` so spawned agents can call it.
- **Gateway route** (`gateway/gateway/unclaimed-handler.ts`, wired in `gateway-entry.ts` + `server.ts`):
  verifies the Firebase token with an **open-to-all authenticator** (the same verify + email-verified
  floor as the other lanes, but the allowlist is SKIPPED so any signed-in user qualifies), rate-limits,
  then forwards to the unclaimed-check service with the server-side key.
- **Bundled skill** (`.claude/skills/unclaimed-check/SKILL.md`): the agent SOP — installed into
  `~/.claude/skills` only when the flag is on (integration manifest `cliSkillIds:['unclaimed-check']`
  + `featureFlag:'unclaimedCheckEnabled'`).

### Rollout / dark-landing

Ships `in-development` (OFF). The gateway route is additionally **secret-gated**: it returns `503` until
both `UNCLAIMED_CHECK_URL` and the `gateway-unclaimed-key` secret (`UNCLAIMED_CHECK_KEY`) are configured
and the gateway is redeployed — a separate, human-gated production step. So landing to master changes
nothing observable. GA = flip the flag to `shipped` (a reviewed one-line edit). Rollback = flag back to
off (the local route 404s, the skill uninstalls on next launch) or drop the secret + redeploy (the
gateway route 503s).

## Related

The unclaimed-property lookup is one of the agent-only capabilities an agent calls on your behalf, in the same family as the messaging routes described on [Agent tools](agent-tools.md). Because those routes need bearer authentication, the local server they answer on is documented on [CLI Control](cli-control.md). An agent that has to reach a third-party service with someone else's account is covered by [Automation credentials](automation-credentials.md).