Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,26 @@
Notable changes to this service, newest first, per release. This file is written for whoever
runs the service or integrates against it.

## v0.12.0

### Added

- **An AI app's connection is named, listed and signed out.** When the app redeems its code the connection gets a
public name, its time of connecting and a place in its assistant's index; its app tokens state the name as `sid`.
`GET /identity/connections` lists the apps connected as the caller's own assistants in their workspace, and
`DELETE /identity/connections/{id}` signs one out; `GET`, `DELETE /identity/assistants/{assistant}/connections[/{id}]`
do the same for an administrator of the workspace (`membership:admin`), any person's, and end them all. Each takes a
person's own token only. A sign-out is recorded as a security event (`connection_signed_out`) naming who did it.

### Changed

- **An AI app's token stops at once when its connection ends.** Its exchange is refused, `401 err:connection:ended`,
unless the connection its `sid` names is live and still its person's, app's and assistant's, though the token has
not expired; a live one is marked used, at most once a minute. An app token minted before this version names no
connection and is refused at its next exchange, so an app connected before it signs in again. An exchanging
client that keeps passes made from app tokens should ask for one at every call (go-authbyte's
`ExchangeDelegatedToken`), or a kept pass outlives the sign-out.

## v0.11.0

### Changed
Expand Down
14 changes: 13 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,11 @@ Endpoints are registered in [`routes/router.go`](routes/router.go). The two opti
| `GET /identity` | The internal identity plus `loa`, `login_method` and, to a token of a client whose row says `signing: true`, the signing flows that method permits. A token for any enabled sign-in client's audience is accepted | valid user token (DPoP) |
| `POST /identity/persons` | Register a person before their first login: the identity code (any spelling; stored canonical) and the name create the person row with a stable subject and **no credential** — the subject an administrator then invites them to a membership register under. Idempotent on the code: `201` created, `200` already known (names filled only where the row has none); a code naming no country or an unknown identity type is `422 err:identity:invalid` (never echoed) | valid token carrying `identity:admin` (DPoP) |
| `POST /identity/persons/lines` | Read, for up to 500 people at once (`{"subjects": ["sub:<id>", …]}`), whether each can sign in and what is known about how: the email a directory sign-in left (only when one is kept) and, for a person holding a national identity code, its country and displayed length — **never the code**. A person the platform does not know is left out. More than 500, an empty or non-list body or a malformed subject is `422 err:identity:invalid` (the values sent are never repeated). Answered `Cache-Control: no-store` | a **service acting as itself** (its own token: subject `svc:…`, naming no organisation and no actor) carrying `identity:lines` — a person's token, a token exchanged to act for someone and a service account's token for an organisation never read it, even holding the scope (DPoP) |
| `GET /identity/connections` | The AI apps connected as the caller's own assistants in the workspace their token names: `{"assistants": [{"key", "name", "connections": [{"id", "app", "connectedAt", "lastUsed"}]}]}`, an assistant with none listed with none, newest connection first, `lastUsed` `null` until a call went through. `502 err:upstream:unavailable` when the register cannot answer which assistants are theirs; `no-store` | a **person's own token** naming a workspace (no actor, not an AI app's, not a service's): otherwise `403 err:connection:forbidden` (DPoP) |
| `DELETE /identity/connections/{id}` | Sign out one of the caller's own connected apps by its public name: its session and refresh token end, its app's next exchange is refused at once, the person's others go on; recorded as a security event naming the doer. `204`; `404 err:connection:not_found` for a name that is not theirs, or not live | as above |
| `GET /identity/assistants/{assistant}/connections` | The AI apps connected as one assistant of the workspace the token names, any person's: `{"connections": [{"id", "app", "connectedAt", "lastUsed"}]}`. Another workspace's assistant reads as having none; a key not shaped `svc:assistant-<ULID>` is `404` | a person's own token holding the register's administering level, `membership:admin`; otherwise `403` (DPoP) |
| `DELETE /identity/assistants/{assistant}/connections/{id}` | Sign out one app connected as the assistant, as the person's own sign-out does, the administrator recorded as the doer. `204`; `404` when it is not that assistant's live connection in this workspace | as above |
| `DELETE /identity/assistants/{assistant}/connections` | Sign out every app connected as the assistant, at once (what its removal asks first). `204`, with none to end as well | as above |
| `GET /identity/persons/{personSub}/code` | Read one person's national identity code the way a person is shown it, with its country: `{"code": "…", "country": "LV"}`. A person not known, or holding no code, is `404 err:identity:not_found`; a malformed id is `422 err:identity:invalid`. Each code answered is recorded with the access audit as a routine read of the person by the calling service (`identity.read`, marked `identityCode`, never the code); the caller records the disclosure it makes onward. Answered `Cache-Control: no-store` | a **service acting as itself** carrying `identity:code`, refused as the lines read refuses — a grant for `identity:lines` never reaches a code (DPoP) |
| `POST /authorize/card` | The sign-in page's card answer: the card signed the challenge the page was shown with. Its address carries the client's request, checked again; it needs the browser's binding cookie, the page's token, an `Origin` equal to `BASE_URL`'s and a challenge that browser was given; the engine checks the token, and the browser goes back to the client with a code (303), or to the page | anonymous (the page's browser) — **only if `WEBEID_ENGINE_URL` set** |
| `GET /.well-known/jwks.json` | Signing public keys (active + retired-within-window) | anonymous |
Expand Down Expand Up @@ -391,7 +396,14 @@ answers a new one, and one used again ends that connection. **Every refresh asks
the assistant removed or given to another person, or the person gone from the workspace, ends the
connection; a box the assistant lost is gone from the next token. A connection is a session of its own,
not the browser's shared one, lasting at most `SESSION_TTL`; the app ends it at `/revoke` with its
refresh token and no key, which ends nothing else. **A token exchanged from an AI app's token** (its
refresh token and no key, which ends nothing else. **A connection is named and listed:** when the app redeems its
code the connection gets a public name of its own (never its session's key or a token), its time of connecting, and a
place in its assistant's index (per workspace and assistant, until the connection's end); each app token states that
name as its `sid`. **It stops at once when it ends:** an exchange of an AI app's token is refused, `401
err:connection:ended`, unless the connection its `sid` names is live, still the token's person's, app's and
assistant's, though the token itself has not expired; a live one is marked used, at most once a minute. A person
lists the apps connected as their own assistants and signs one out; a workspace's administrator does the same for an
assistant's, and ends them all when it is removed (the `/identity/connections` routes, above). **A token exchanged from an AI app's token** (its
`login_method` is `assistant`) carries no box (`service/feature:act`) the app token lacks, at every hop, whatever the
exchanging client's grant allows. A level (`group:level`) of the exchanging client's own grant passes only where its
grant toward that audience names it under `assistant_levels`, so a service can still do its own work for the person,
Expand Down
6 changes: 6 additions & 0 deletions app.go
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,12 @@ type SessionStore interface {
LoadShared(ctx context.Context, id string) (*session.Shared, error)
PutSharedApp(ctx context.Context, id, client, sid string, until time.Time) (string, error)
EndShared(ctx context.Context, id string) (map[string]string, error)
// AddConnection keeps an AI app's connection in its assistant's index, by
// workspace and assistant, until until; Connections answers the index's live
// ones; RemoveConnection takes one out, and is no error when it is gone.
AddConnection(ctx context.Context, tenant, assistant string, c session.Connection, until time.Time) error
Connections(ctx context.Context, tenant, assistant string) ([]session.Connection, error)
RemoveConnection(ctx context.Context, tenant, assistant string, c session.Connection) error
Ping(ctx context.Context) error
}

Expand Down
15 changes: 15 additions & 0 deletions audit/audit.go
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,21 @@ func (r *Recorder) SessionEnded(ctx *azugo.Context, actorID, method string) {
actorRef(actorID, "user", ""), attrs)
}

// ConnectionSignedOut records an AI app's connection signed out by a person, its
// own, or by an administrator of its workspace: actorID did it, personID's app
// (clientID) stopped.
func (r *Recorder) ConnectionSignedOut(ctx *azugo.Context, actorID, personID, clientID string, byAdministrator bool) {
by := "person"
if byAdministrator {
by = "administrator"
}

r.emit(ctx, secevents.EventAuthentication, secevents.SeverityInfo, broker.OutcomeSuccess,
actorRef(actorID, "user", ""), map[string]any{
secevents.AttrKind: "connection_signed_out", "person": personID, "client": clientID, "by": by,
})
}

// Logout records the browser's leg of a sign-out. It names no person: the
// session is ended server to server (SessionEnded), and the browser's address
// carries no value that names it. Federated indicates the browser was sent on to
Expand Down
4 changes: 2 additions & 2 deletions issuer/delegated_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ func TestIssueDelegatedActsForUser(t *testing.T) {
t.Fatalf("IssueUser: %v", err)
}

subject, err := iss.ParseSubjectToken(userTok)
subject, _, err := iss.ParseSubjectToken(userTok)
if err != nil {
t.Fatalf("ParseSubjectToken: %v", err)
}
Expand Down Expand Up @@ -144,7 +144,7 @@ func TestExchangeActorChainNests(t *testing.T) {
func TestParseSubjectTokenRejectsGarbage(t *testing.T) {
iss, _, _ := newStack(t)

if _, err := iss.ParseSubjectToken("not-a-jwt"); err == nil {
if _, _, err := iss.ParseSubjectToken("not-a-jwt"); err == nil {
t.Fatal("expected ParseSubjectToken to reject a non-token")
}
}
52 changes: 37 additions & 15 deletions issuer/issuer.go
Original file line number Diff line number Diff line change
Expand Up @@ -112,28 +112,48 @@ type AppTokenInput struct {
Assistant string // the assistant's key, svc:assistant-<ULID>
LoA string // always the lowest: the app holds no sign-in of its own
LoginMethod string // always identity.LoginAssistant
TTL time.Duration
// Connection is the connection's public name, stated as the token's sid, so
// an exchange can tell whether the connection the token was made for is
// still live; "" names none, and such a token is exchanged for nothing.
Connection string
TTL time.Duration
}

// appClaims are an AI app's token's claims: an access token's, and the
// connection it was made for [OIDC Front-Channel Logout 1.0 §3, the sid claim].
type appClaims struct {
claims.Claims

SID string `json:"sid,omitempty"`
}

// IssueApp mints an AI app's token: a plain bearer token, with no cnf, since an
// AI app holds no proof-of-possession key [MCP 2026-07-28 basic/authorization];
// the one kind of token this issuer mints unbound, kept to its one resource by
// its audience and to minutes by its lifetime.
// its audience, to minutes by its lifetime, and to its connection by its sid.
func (i *Issuer) IssueApp(in AppTokenInput) (string, int64, error) {
if in.Assistant == "" || in.TTL <= 0 {
return "", 0, fmt.Errorf("issuer: an app token names its assistant and its lifetime")
}
c := claims.Claims{
RegisteredClaims: i.base(in.Subject, in.Audience, in.TTL),
Scope: strings.Join(in.Scopes, " "),
LoA: in.LoA,
LoginMethod: in.LoginMethod,
Tenant: in.Tenant,
ClientID: in.ClientID,
Act: &claims.Actor{Subject: in.Assistant},
c := appClaims{
Claims: claims.Claims{
RegisteredClaims: i.base(in.Subject, in.Audience, in.TTL),
Scope: strings.Join(in.Scopes, " "),
LoA: in.LoA,
LoginMethod: in.LoginMethod,
Tenant: in.Tenant,
ClientID: in.ClientID,
Act: &claims.Actor{Subject: in.Assistant},
},
SID: in.Connection,
}

tok, err := i.km.SignTyped(c, typeAccessToken)
if err != nil {
return "", 0, err
}

return i.sign(c, in.TTL)
return tok, int64(in.TTL.Seconds()), nil
}

// DelegatedTokenInput describes an on-behalf-of token minted via token
Expand Down Expand Up @@ -184,14 +204,16 @@ func (i *Issuer) IssueDelegated(in DelegatedTokenInput) (string, int64, error) {
// audience is not checked here: a subject token's audience is the previous hop
// (e.g. the portal API), not this endpoint, and which hops a client may act from
// is the registry's to say, so the exchange checks it (registry.MayActFrom).
func (i *Issuer) ParseSubjectToken(raw string) (*claims.Claims, error) {
// Beside the claims it answers the connection the token names: an AI app's
// token's sid, "" for every other token.
func (i *Issuer) ParseSubjectToken(raw string) (*claims.Claims, string, error) {
parser := jwt.NewParser(
jwt.WithValidMethods([]string{i.km.Alg()}),
jwt.WithIssuer(i.issuerURL),
jwt.WithExpirationRequired(),
)

var c claims.Claims
var c appClaims
if _, err := parser.ParseWithClaims(raw, &c, func(tok *jwt.Token) (any, error) {
// Only an access token is exchanged; an ID token signed with the same
// key is refused by its type [RFC 9068 §5].
Expand All @@ -206,10 +228,10 @@ func (i *Issuer) ParseSubjectToken(raw string) (*claims.Claims, error) {

return pk, nil
}); err != nil {
return nil, err
return nil, "", err
}

return &c, nil
return &c.Claims, c.SID, nil
}

func (i *Issuer) base(subject, audience string, ttl time.Duration) jwt.RegisteredClaims {
Expand Down
4 changes: 2 additions & 2 deletions issuer/issuer_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -218,10 +218,10 @@ func TestAnIDTokenIsNoSubjectTokenForAnExchange(t *testing.T) {
if typ := headerType(t, id); typ != "JWT" {
t.Errorf("the ID token is typed %q, want JWT", typ)
}
if _, err := iss.ParseSubjectToken(access); err != nil {
if _, _, err := iss.ParseSubjectToken(access); err != nil {
t.Errorf("the access token was refused as a subject: %v", err)
}
if _, err := iss.ParseSubjectToken(id); err == nil {
if _, _, err := iss.ParseSubjectToken(id); err == nil {
t.Error("the ID token was accepted as the subject of an exchange")
}
}
Expand Down
Loading
Loading