5.4 SessionKeyManager

1. Bot Identity

Operational profile

2. Purpose

Issue, scope, and expire short-lived session keys so strategies can sign without re-prompting on every order.

3. Why This Bot Matters

• Session key never expires

  A compromised key allows unlimited signing indefinitely without re-authorisation.

• Key scope not strategy-bound

  A key issued for one strategy could sign orders for another, violating least-privilege.

• No emergency revocation path

  A stolen key cannot be neutralised quickly, extending the attack window.

No worked examples on this bot yet. Worked examples are optional but strongly recommended — they turn an abstract failure mode into something a developer can verify in a fixture.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "max_session_lifetime_h": 8 }

if (session.age_h >= p.max_session_lifetime_h) return reject('SESSION_KEY_EXPIRED');

{ "max_calls_per_session": 1000 }

if (session.call_count >= p.max_calls_per_session) return reject('SESSION_KEY_EXPIRED');

8. Default Configuration

{
  "bot_id": "sec.session_key_manager",
  "version": "0.1.0",
  "mode": "hard_guard",
  "defaults": {
    "max_session_lifetime_h": 8,
    "max_calls_per_session": 1000,
    "scope_per_strategy": true,
    "auto_revoke_on_idle_h": 2
  }
}

9. Implementation Flow

1. Receive session key request or signing call.
2. Check KillSwitch; if active, revoke all session keys and REJECT(KILL_SWITCH_ACTIVE).
3. For new key request: issue key with scope (strategy_id, methods, max_size, expiry=now+max_session_lifetime_h).
4. For signing call: verify key exists and is not expired (age check).
5. Verify call_count < max_calls_per_session; if exceeded, REJECT(SESSION_KEY_EXPIRED).
6. Verify idle duration < auto_revoke_on_idle_h; if exceeded, revoke and REJECT(SESSION_KEY_EXPIRED).
7. Increment call_count; emit RiskVote(APPROVE).
8. Log session event to governance audit trail.

10. Reference Implementation

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. IF/THEN/ELSE = decision. Translate directly to TypeScript, Python, Go, or Rust.

// SessionKeyManager
FUNCTION validateSession(signingCall, sessions):
  IF FETCH(internal.killswitch).active:
    FOR session IN sessions.active: session.revoke()
    EMIT RiskVote(DENY, KILL_SWITCH_ACTIVE); RETURN
  session = sessions.get(signingCall.session_id)
  IF session == null:
    EMIT RiskVote(DENY, SESSION_KEY_EXPIRED); RETURN
  // Lifetime check
  age_h = (NOW() - session.issued_at) / 3600
  IF age_h >= params.max_session_lifetime_h:
    session.revoke()
    EMIT RiskVote(DENY, SESSION_KEY_EXPIRED); RETURN
  // Call budget check
  IF session.call_count >= params.max_calls_per_session:
    session.revoke()
    EMIT RiskVote(DENY, SESSION_KEY_EXPIRED); RETURN
  // Idle check
  idle_h = (NOW() - session.last_used_at) / 3600
  IF idle_h > params.auto_revoke_on_idle_h:
    session.revoke()
    EMIT RiskVote(DENY, SESSION_KEY_EXPIRED); RETURN
  session.call_count += 1
  session.last_used_at = NOW()
  EMIT RiskVote(APPROVE)
  LOG(governance.audit, {session_id, call_count})

SDK calls used

• clob_auth.issue_session_token(scope)
• internal.killswitch.status()

Complexity: O(1) per call — hash map session lookup

11. Wire Examples

Input — what arrives on the wire

Signing call with active session — internal

{
  "intent_id": "int_4d5e6f7a8b9c0d1e",
  "session_id": "sk_4e5f6a7b8c9d0e1f",
  "strategy_id": "strat.sports_model",
  "timestamp_ms": 1746768672000
}

Output — what the bot emits

RiskVote — APPROVE

{
  "vote_id": "sec.session_key_manager.20260509T150000Z",
  "decision": "APPROVE",
  "reason_code": null,
  "evidence": {
    "session_id": "sk_4e5f6a7b8c9d0e1f",
    "calls_remaining": 958
  },
  "checked_at": "2026-05-09T15:00:00Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "vote_id": "sec.session_key_manager.20260509T150000Z",
  "decision": "APPROVE",
  "reason_code": null,
  "evidence": {
    "session_id": "sk_4e5f6a7b8c9d0e1f",
    "age_h": 2.5,
    "call_count": 42,
    "calls_remaining": 958,
    "scope": "strat.sports_model"
  },
  "checked_at": "2026-05-09T15:00:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "sec.session_key_manager",
  "decision": "APPROVE",
  "inputs_used": [
    "session.age_h",
    "session.call_count",
    "session.scope"
  ],
  "checked_at": "2026-05-09T15:00:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

Reload active sessions from persistent store on restart; expired sessions discarded.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

Used by (auto-aggregated)

5.1 5.5

External services

23. Security Surfaces

Abuse vectors considered

• Session token theft enabling signing calls beyond user intent
• Call count manipulation to reset budget and extend session

Mitigations

• Session tokens are scoped to a single strategy_id and methods list
• call_count is server-side authoritative; never trusted from client

24. Polymarket V2 Compatibility

API surfaces declared

Networks supported

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

Session key events are routine security hygiene; mass expiry or zero-active alerts require immediate investigation.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/sessionkeymanager → green if Session store reachable; at least 1 active session for active strategies.; red if Session store unreachable or zero active sessions while strategies running.

28. Promotion Gates

A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.

Promote to Shadow

Promote to Limited live

Promote to General live

29. Developer Checklist

Ready-to-ship score: 27/27 sections complete · 100%