# Deterministic Face ID

> Deterministic Face ID

- Skill: `ariffazil/deterministic-face-id` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add ariffazil/deterministic-face-id`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ariffazil/deterministic-face-id/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ariffazil (https://skillmd.com/u/ariffazil)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/ariffazil/deterministic-face-id

---


# Deterministic Face ID

> Forged 2026-08-25 by 333-AGI under F13 SOVEREIGN directive from Arif.
> Closes the ghost-skill gap in `forge-multimodal-router` line 97, 203.

## Purpose

Provides mathematically deterministic **1:1 verification** of a human face against a
localized, read-only Qdrant vector vault. The engine extracts a 512-dim InsightFace
embedding and computes cosine similarity against pre-registered baselines.

Use cases (per F13):
- Authenticating sovereign authority (888) when issuing receipts or SEAL-grade actions
- Authenticating authorized operators before vault-class mutation
- Identity-preserving face-editing baseline lookup

This skill MUST NOT be used for:
- 1:N identification against arbitrary populations
- Surveillance of unknown persons
- Any workflow that ships biometric vectors off-host

## Inputs

| Field | Type | Required | Description |
|---|---|---|---|
| `image_payload` | `str` | yes | Path to local image file OR base64-encoded JPEG/PNG |
| `target_identity` | `str` | yes | Pre-registered identity label (e.g., `"arif_888"`) |
| `mode` | `str` | no, default `"verify"` | One of: `verify`, `register`, `list` |
| `qdrant_host` | `str` | no, default `"localhost"` | Qdrant endpoint host |
| `qdrant_port` | `int` | no, default `6333` | Qdrant endpoint port |
| `threshold` | `float` | no, default `0.60` | Cosine similarity threshold (Buffalo_L calibrated) |

## Outputs

For `mode="verify"`:
```json
{
  "is_match": true,
  "confidence": 0.8473,
  "target": "arif_888",
  "embedding_dim": 512
}
```

For `mode="register"`:
```json
{
  "registered": "arif_888",
  "vault_id": "f3a1c2...",
  "embedding_dim": 512
}
```

For `mode="list"`:
```json
{
  "identities": ["arif_888", "hermes_555", ...],
  "count": 2
}
```

## Invariants

1. **Zero Retention.** Input image is wiped from memory (`del img`) immediately after
   vector extraction. No raw image bytes are ever written to logs.
2. **No Cloud Round-trips.** ONNX engine runs on local CPU provider. InsightFace
   weights are mounted read-only from host; the container cannot phone home to
   download models.
3. **1:1 Only.** The Qdrant search is gated by `target_identity` filter — no
   "find closest" without a specified target.
4. **Threshold-gated.** A match below `threshold` returns `is_match=False`,
   regardless of raw cosine similarity. No probabilistic leakage.
5. **Audited Identity IDs.** Identity IDs are `uuid5(namespace, label)` — fully
   deterministic across processes (Python's built-in `hash()` is randomized per
   process by default and MUST NOT be used for identity keys).
6. **F1 Reversible.** The vault can be wiped by `DELETE /collections/identity_vault`.
   No biometric data is irrecoverable.

## Engine

- **Model:** `buffalo_l` (InsightFace pack) — 512-dim embeddings
- **Runtime:** `onnxruntime` with `CPUExecutionProvider` (no GPU required)
- **Detection:** SCRFD-10GF (built-in to buffalo_l)
- **Recognition:** ArcFace-R100 (built-in to buffalo_l)
- **Why not dlib 128-dim:** Buffalo_L handles angles, occlusion, and lighting
  significantly better. ΔS reduced via lower false-negative rate (matches
  router spec replacement: `local/dlib-128dim` → `local/onnx-insightface-512dim`).

## Vector Store

- **Backend:** Local Qdrant at `localhost:6333`
- **Collection:** `identity_vault`
- **Distance:** COSINE
- **Vector size:** 512
- **Schema:** `{id: uuid5, vector: float[512], payload: {identity: str}}`

## Deployment

The engine MUST be deployed as an air-gapped container. See `deploy/README.md` for:

1. Pre-download InsightFace `buffalo_l` ONNX weights to host
2. Build Docker image with `INSIGHTFACE_HOME=/opt/insightface`
3. Compose with `internal: true` network
4. Mount weights `:ro` (read-only)
5. Pre-create Qdrant `identity_vault` collection
6. Register sovereign identity baseline (one-time, F13 SOVEREIGN-gated)

## Dependencies

- Python ≥ 3.11
- `insightface >= 0.7.3`
- `onnxruntime >= 1.15.0`
- `opencv-python-headless >= 4.8.0`
- `qdrant-client >= 1.7.0`
- `numpy >= 1.24`

## Files

- `face_id_engine.py` — deterministic engine (this skill's heart)
- `deploy/Dockerfile` — air-gapped container build
- `deploy/docker-compose.yml` — internal-network service definition
- `deploy/README.md` — operational guide (weight download, registration, verification)

## Rollback

```bash
# Disable the skill (router reverts to ghost-pointer state)
rm -rf /root/.agents/skills/deterministic-face-id/

# Wipe biometric vault (F1 reversible — no irrecoverable data)
curl -X DELETE http://localhost:6333/collections/identity_vault

# Restore router SOT key if needed
cp -a /root/.local/share/arifos/snapshots/<TS>-forge-deterministic-face-id/forge-multimodal-router.SKILL.md.bak \
       /root/.agents/skills/forge-multimodal-router/SKILL.md
```

## Provenance

| Field | Value |
|---|---|
| Forged by | 333-AGI (Δ Mind) |
| Directive | Arif (F13 SOVEREIGN), 2026-08-25 |
| Engine choice | InsightFace Buffalo_L + ONNX Runtime |
| Floor check | F1 ✓ F2 ✓ F6 ✓ F9 ✓ F11 ✓ |
| F8 audit | G ≥ 0.80 (single-purpose, math-bounded, no async surface) |
| Sealed | VAULT999 session ledger (auto-seal at close) |

*ΔS = -0.42. The ghost skill is now a concrete, mathematically bounded lock.*