Documentation

iamsec is a policy engine for permission that has to be re-earned.

It issues short-lived, scope-limited grants between two or more subjects, evaluates every call against them, and invalidates everything the moment any one party withdraws. That is the entire product. Everything else in these docs is detail.

What it is, and what it deliberately is not

iamsec sits beside your identity provider, not underneath it. It does not authenticate anyone — federation handles that. It answers a narrower and much more interesting question: given two identities that are already known to each other, what is each one allowed to do to, with, or on behalf of the other, right now, and for how long?

It is not a dating product, not a directory, and not a messaging system. There is no discovery surface of any kind. A policy cannot be created between two subjects who have not both already been issued identifiers, and there is no endpoint that would let you look one up.

Five-minute negotiation

This walkthrough takes a brand-new pair from nothing-granted to a live session and then revokes it. Every command is real against the sandbox tenant.

Install and authenticate

The CLI never stores a long-lived token on Coven, and on every other plan the session token dies with the terminal.

npm i -g @iamsec/cli
iamsec login --factor verbal
# → browser opened, written factor recorded, verbal factor captured locally
# → never transmitted; only its hash and timestamp are stored

Declare your limits before you claim any access

Order matters socially, and the engine enforces it technically: a subject with zero declared limits cannot be a counterparty to a critical-risk scope.

iamsec limit declare body:spine --type hard
iamsec limit declare substances:receiver --type hard
iamsec limits list --me
# 2 hard · 0 soft · immutable=true

Draft, propose, then narrow

iamsec policy draft --scope scene.open --scope contact.sensation \
                      --window 90m --checkin 15m --safeword RED
iamsec policy propose --to b-4417
# policy/8f21 · state=proposed · grants=0 (proposals never grant)

The counterparty narrows independently. Widening requires an explicit second affirmation from the original proposer, which is the whole point of the round trip.

iamsec policy review policy/8f21 --narrow --drop contact.sensation
iamsec policy sign policy/8f21 --factor verbal --factor written
# signed · 1 scope dropped by counterparty · 1 scope remaining

Open a session and watch it end

iamsec session open --policy policy/8f21
# ✓ session sess_01jd9 · expires in 90m · monitor required for 0 scopes

iamsec consent withdraw --me
# ✓ revoked in 0.6ms · 1 grant cleared · aftercare window opened (6h)
# reason: not required, not recorded, not askable-for

How a request is evaluated

Every authorization call is stateless and re-resolves the full policy set. There is no session-level permission cache, only a signature cache, and it never outlives the affirmation that produced it.

{
  "session": "sess_01jd9",
  "actor":   "top/a-2210",
  "subject": "bottom/b-4417",
  "action":  "contact.impact",
  "context": { "monitor_present": true, "sober_attested_at": 41200000 }
}

{
  "decision": "deny",
  "matched_statement": "hard-limit/consent:ongoing",
  "precedence": "explicit_deny",
  "overridable": false,
  "appeal": null,
  "age_of_last_affirmation_ms": 2740000,
  "hint": "affirmation older than scope ceiling; re-negotiate"
}

Note what is missing from that response: there is no field in which the engine tells the actor anything about the subject’s internal state. It tells you the rule that stopped you and the age of a signature. Refusal is not a disclosure.

Where to go next