Alienid Signature Demo

README

# OpenClaw Alien ID Signature Demo

Demo plugin that adds:

- Alien ID setup as part of `openclaw onboard` (when plugin path is available)
- Alien ID SSO binding command (`openclaw alienid login`)
- owner binding (`Alien session -> OpenClaw instance key`)
- per-action signatures for tool/message hooks
- subagent delegation certificates (`main -> subagent`)
- append-only signed audit log with hash chaining
- clear signature traces in OpenClaw console logs
- optional signature marker injected into tool results

## What this proves

For demo purposes, the trust chain is:

1. Alien SSO id token proves owner session (`sub`) for your provider
2. Plugin verifies JWT signature using OIDC discovery + JWKS
3. Plugin binds owner session to OpenClaw main key (`owner-binding.json`)
4. Each action/message is signed by main or subagent key
5. Subagent keys are delegated by a cert signed by main key
6. Audit log stores every signed envelope with previous hash link
7. Owner key proof from Alien app callback is verified and bound into owner binding

## Install

1. Add plugin path to OpenClaw config:

```json5
{
  plugins: {
    load: {
      paths: ["/home/aryeh/devel/alien/openclaw-alienid-signature-demo"]
    },
    entries: {
      "alienid-signature-demo": {
        enabled: true,
        config: {
          providerAddress: "<YOUR_PROVIDER_ADDRESS>",
          ssoBaseUrl: "https://sso.alien-api.com",
          ownerProfileUrl: "https://alien.id/legal",
          oidcOrigin: "http://localhost",
          requireOwnerKeyProof: true,
          openBrowserQr: true,
          injectToolResultSignature: true,
          decorateOutgoingMessages: false,
          verboseConsole: true
        }
      }
    }
  }
}
```

2. Restart OpenClaw.

## Onboard with Alien SSO

Run:

```bash
openclaw onboard
```

During onboarding, choose to enable the Alien ID signature demo and provide your `providerAddress`.
On interactive onboarding, owner binding login now runs inline as part of the flow and opens a browser page that renders a scannable QR code.
When a local OpenClaw gateway is running, the QR is served from that same gateway origin (`/alienid-signature-demo/login-qr?...`); otherwise it falls back to a local file page.
If you skip it, run:

```bash
openclaw alienid login --provider-address <PROVIDER_ADDRESS> --oidc-origin http://localhost
```

If needed, disable browser launch with:

```bash
openclaw alienid login --provider-address <PROVIDER_ADDRESS> --no-browser-qr
```

You can also configure onboarding non-interactively:

```bash
openclaw onboard --non-interactive --accept-risk --alien-id-demo --alien-id-provider-address <PROVIDER_ADDRESS>
```

Then check:

```bash
openclaw alienid status
```

## Signature visibility in OpenClaw console

During runtime you will see explicit lines such as:

- `[AlienID-SIG] TOOL_PRE ...`
- `[AlienID-SIG] TOOL_POST ...`
- `[AlienID-SIG] MSG_SEND ...`
- `[AlienID-SIG] MSG_SENT ...`

If `injectToolResultSignature=true`, tool result transcript messages also get a signature marker line.

## Verify chain

Inside OpenClaw:

```bash
openclaw alienid verify
```

Standalone:

```bash
node /home/aryeh/devel/alien/openclaw-alienid-signature-demo/scripts/verify-audit.mjs
```

`verify` also checks:

- owner proof signature (`session_address + seed` signed by session public key)
- proof subject/provider consistency with owner binding
- owner proof hash embedded in `owner-binding.json`

## Export proof bundle

```bash
openclaw alienid export-proof --out ./alienid-proof-bundle.json
```

Bundle includes owner binding + signed operations for external verification.

## State layout

By default under:

`~/.openclaw/alienid-signatures/alienid-signature-demo/`

Key files:

- `owner-binding.json`
- `owner-session.json`
- `keys/main.json`
- `keys/subagents/*.json`
- `delegations/*.json`
- `audit/operations.jsonl`

## Notes

- This is a demo-level implementation aligned with AAID concepts; it is not on-chain AAID.
- Tokens are stored locally in `owner-session.json` for demo continuity.
- Keep `~/.openclaw/alienid-signatures` protected.