Skip to content

feat(lk): lk sip and lk number use the Public API under --user-auth - #1124

Open
Topherhindman wants to merge 4 commits into
mainfrom
topherhindman/telephony
Open

Topherhindman wants to merge 4 commits into
mainfrom
topherhindman/telephony

Conversation

@Topherhindman

Copy link
Copy Markdown
Contributor

Fixes DEVX-946

Depends on livekit/public-api-server#174, which adds TelephonyService. The client in pkg/public/oapi is generated from that PR's branch (44b6011e). Re-pin it to a public-api-server main commit before this merges.

Why

Under --user-auth, lk sip and lk number reached the SIP API through the CreateToken token bridge. So the role a member needed came from the CreateToken grant mapping, not from the SIP RPC itself. A READ member couldn't list trunks. A WRITE member could buy and release phone numbers, which only ADMIN may do.

What changed

  • pkg/public: the client is regenerated, and telephony.go wraps the TelephonyService RPCs. The data shapes are LiveKit's own messages, so these methods take and return the livekit types. lk already builds and prints those types. A protojson round trip keeps every field, enum, oneof and duration.
  • lk sip inbound|outbound|dispatch list|create|update|delete and lk sip participant create|transfer: with an API key, nothing changes. Under --user-auth, they call the Public API and mint no token. Flags, request files and output are the same in both modes.
    • inbound delete and outbound delete still delete a trunk of either kind by its ID.
    • A refused call or transfer prints its SIP status in both modes. Under --user-auth the status comes from the error's livekit.SIPStatus detail, or from the livekit.SIPTransferError detail of a failed transfer.
    • participant create --agent-name still dispatches the agent through the token bridge, because agent dispatch has no Public API RPC.
  • The hidden legacy SIP commands have no Public API RPC. Under --user-auth, each one names the command that replaces it.
  • lk number search|purchase|list|get|update|release: the same dual mode.
    • The API buys and releases one number for each call. So purchase --numbers a --numbers b and release --ids ... make one call per number. They stop at the first failure and name the numbers already done.
    • Under --user-auth, list pages by cursor. --limit is still the page size. A hidden --cursor takes the next page, which the hint prints. --offset is API-key only.
    • update --name is new, in both modes.

Who can use what under --user-auth: trunks, dispatch rules and numbers need ADMIN, and placing or transferring a call needs WRITE.

How it was tested

  • go build ./..., go vet ./..., go test -race ./... and golangci-lint run ./... all pass.
  • Unit tests in pkg/public/telephony_test.go check the request bodies and query parameters, the protojson round trip (enums, durations, oneof replace/update, ListUpdate), a request file that uses proto field names, paging, and the SIP status detail on a refused call.
  • Testscripts (cmd/lk/testdata/script) run under --user-auth against the fake Public API:
    • trunks, dispatch rules, participants, and a refused call;
    • every number command, list paging, and a 403 that names ADMIN;
    • the legacy refusals.
    • Each one asserts the /v0 route that lk called, and that lk minted no token.
  • telephony-with-api-key.txtar shows that the API-key path still calls the project's SIP API with the key.
  • Against a local public-api-server on this PR's base branch, reading staging (project "topher test"): lk --user-auth sip inbound create|list|update|delete and sip dispatch create|list|delete worked, a conflicting trunk printed the SIP API's own message, and the API-key path (Homebrew lk and this branch) listed the same rules. number search worked with an API key; under --user-auth it answered Unavailable, because a laptop can't reach sip-api.

Open question

  • lk number list under --user-auth. It shows one page per run and prints a hint with the next --cursor. Should it fetch every page instead, so one run lists all of a project's numbers?

Generated from livekit/public-api-server@44b6011

That commit is on the unmerged topherhindman/telephony branch, which
adds TelephonyService. Re-pin to a public-api-server main commit before
this merges.
Trunks, dispatch rules, SIP participants and phone numbers. Their data
shapes are LiveKit's own messages, which the API sends as protojson,
so these methods take and return the livekit types that lk's sip and
number commands already build from flags and request files and print.
A protojson round trip keeps every field, enum, oneof and duration;
the generated client still makes each request, so the paths and query
parameters come from the spec.

A call that the far end refuses keeps its APIError and also unwraps to
the livekit.SIPStatus detail, so livekit.SIPStatusFrom finds it.
Under --user-auth, lk sip reached the SIP API through CreateToken's
token bridge, so whether a member could use it depended on which grant
CreateToken maps to which role, not on the role the SIP RPC needs. The
trunk, dispatch rule and participant commands now call the Public API's
TelephonyService, which checks the role itself (ADMIN for trunks and
rules, WRITE for calls) and mints no token.

- Each command takes a sipAPI: server-sdk-go's SIPClient with an API
  key, as before, or publicSIP under --user-auth. Flags, request files
  and output are the same in both modes.
- sip inbound|outbound delete still delete a trunk of either kind by
  its ID: an ID that isn't an inbound trunk is tried as an outbound one.
- A refused call prints its SIP status in both modes.
- participant create --agent-name still dispatches the agent through
  the token bridge: agent dispatch has no Public API RPC.
- The hidden legacy commands (list-sip-trunk, create-sip-dispatch-rule,
  ...) have no Public API RPC, so under --user-auth they point to the
  command that replaces them.

Tested: testscripts for trunks, dispatch rules, participants, a refused
call, the legacy refusals, and the API-key path still calling the SIP
API with the key.
lk number reached the SIP API's phone-number service through
CreateToken's token bridge under --user-auth, so a WRITE member could
buy and release numbers. The commands now call the Public API's
TelephonyService, which needs ADMIN for every number RPC until it
checks RBAC permissions.

- search, purchase, get, update and release take a phoneNumberAPI:
  server-sdk-go's client with an API key, as before, or
  publicPhoneNumbers under --user-auth.
- The Public API buys and releases one number for each call, so
  purchase --numbers and release --ids|--numbers make one call for
  each, in order, and stop at the first failure, naming the numbers
  already done.
- list pages by cursor under --user-auth: --limit is still the page
  size, a hidden --cursor takes the next page that the hint prints, and
  --offset stays API-key only. The user-auth list reads its page once,
  not twice as the API-key path does.
- update takes --name in both modes.

Tested: testscripts for each number command, list paging, a refusal
that names ADMIN, and the API-key path; unit tests for the partial
purchase and release errors.

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 1 potential issue.

1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

Devin Review

Comment thread cmd/lk/sip.go
Comment on lines +1295 to +1298
if userAuthEnabled(cmd) {
if _, err := requireProjectForSDK(ctx, cmd); err != nil {
return err
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Agent dispatch targets the wrong project

With multiple projects and no default, --agent-name prompts twice and can select different projects. requireProjectForSDK resolves the project again after telephonyProject selects one. The agent joins the second project while the SIP call uses the first.

Learn more

A user-auth SIP call selects its Public API project in telephonyProject. Agent dispatch then loads a separate SDK project through requireProjectForSDK, which uses resolveProjectRef again. When no default or explicit project exists, each resolution invokes pickUserProject independently. Selecting different projects puts the dispatch and call in different rooms, despite identical room names.

Example: A user can access projects A and B, with neither selected as default. They run lk --user-auth sip participant create --agent-name bot --trunk ST_1 --to +15550100 and select A, then B. The agent dispatch goes to B while the call is created in A.

Recommended fix: Resolve the project once and reuse its ID for both telephony calls and the token-bridge SDK client. Pass the selected ID into the session-project loading path, or create the SDK project configuration from that same selection without invoking a second picker.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

@Topherhindman
Topherhindman requested review from a team and rektdeckard November 13, 2026 03:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant