# 0014 Tokens from an external issuer

Sources: [\#487](<https://github.com/eizedev/pivotkit/issues/487>), [the decision on \#487](<https://github.com/eizedev/pivotkit/issues/487#issuecomment-6943482229>)

## Context and Problem Statement

PowerShell Universal knows who is signed in to it. It should hand that person a short-lived pivotkit token without a sign-in provider. How does pivotkit-server accept such tokens, and how much may they carry?

## Considered Options

- An HMAC key shared with the other system.
- An Ed25519 key pair: the other system holds the private key, pivotkit only the public one.
- The other system's tokens carry what they claim: every scope without a `scope` claim, any configured profile.
- The other system's tokens are capped by what the operator allows for that issuer.

## Decision Outcome

Chosen options: the Ed25519 key pair, with caps per issuer.

- `auth.externalIssuers` names the issuer, its token type and one or two public keys.
- Each issuer is checked with its own name, type and keys only.
- `scopes` is required. A token's `scope` is cut to it, and a token without `scope` gets exactly that list, never every scope.
- `profiles` lists the profiles a token may name. Any other gets 401. `profile` is the issuer's profile for a token that names none, else `auth.defaultProfile`.
- A token always resolves to a profile the operator chose. A configuration without the issuer's `profile` and without `auth.defaultProfile` is refused. The sources' own policy never applies.
- These tokens get no links or uploads bound to a sign-in, and token exchange stays refused.
- There is no deny list. `maxMinutes` caps a token's lifetime (default 60, at most 1440).
- The tokens carry no audience.

Why the key pair: \#487 prefers it, so pivotkit can never mint tokens for the other system.

Why the caps: the other system is a sign-in provider, not an operator. Its tokens never get more than the operator allowed it.

Why there is no deny list and no audience: the tokens are kept short (`maxMinutes`) instead.

### Not decided

- The PowerShell Universal side: the function that mints the tokens.
- Key rotation beyond two keys per issuer.
- Limits per person.

### Consequences

- A leaked token works until it expires, at most `maxMinutes`.
- Every pivotkit-server that trusts the same public key accepts the same token.
- A stolen private key of the issuer makes tokens for any person, within the issuer's scopes and profiles.
- Operators keep `maxMinutes` low and give each issuer only the scopes and profiles it needs.
- [0009](<https://pivotkit.eize.dev/decisions/0009-server-signed-tokens/index.md>) and [0010](<https://pivotkit.eize.dev/decisions/0010-signed-tokens-without-audience/index.md>) cover the tokens the server signs itself.
