Skip to content

feat(keys): support auth-key node attributes - #112

Merged
jaxxstorm merged 3 commits into
mainfrom
automation/tailscale-api-auth-key-node-attributes
Nov 7, 2026
Merged

jaxxstorm merged 3 commits into
mainfrom
automation/tailscale-api-auth-key-node-attributes

Conversation

@jaxxstorm

@jaxxstorm jaxxstorm commented Nov 7, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • Add tscli create key --node-attributes '<JSON object>' for auth keys, serialized at capabilities.devices.create.nodeAttributes.
  • Validate nonempty custom: names, at most 100 attributes, and string/integer-literal/boolean values before initializing the API client. Preserve large integers without float64 conversion and preserve existing capability flags, description, expiry, and default omission behavior.
  • Use a local request model through the existing authenticated HTTP transport because the pinned Tailscale SDK does not model this property. Share the capability model with property-coverage analysis.
  • Preserve returned node attributes in auth-key creation, get key, and list keys (including --all) through a local response model that retains SDK metadata. Keep the existing single-object/list-array output shapes.
  • Preserve exact numbers through final JSON and YAML printers; avoid float64 rounding of large posture integers.
  • Refresh the official OpenAPI snapshot/metadata, register key response-property coverage, regenerate coverage evidence and command docs, and document the additional caller permission.

Upstream evidence and scope

Source: Tailscale's official API v2 OpenAPI schema, KeyCapabilities.devices.create.nodeAttributes and the createKey operation description. Newly observed by the API watcher on November 7, 2026; this is an observation date, not a claimed release date. The changelog did not announce a corresponding new entry.

The calling OAuth credential needs devices:posture_attributes in addition to auth_keys. The command's --scope flag does not grant permissions to its caller. This flag is rejected for OAuth-client and federated-credential creation. Numbers use JSON integer literals (not decimal/exponent notation).

The successful POST /tailnet/{tailnet}/keys and GET /tailnet/{tailnet}/keys/{keyId} responses reference Key; the list response contains keys[] of Key. Key.capabilities references KeyCapabilities, so node attributes are part of these response contracts too. The confirmed SDK field-loss gap is fixed for auth-key creation/get/list, and these response properties are now covered rather than hidden behind default exclusions. Existing OAuth/federated creation requests remain unchanged; the schema limits device capabilities to auth keys.

No SDK/dependency upgrade, real tailnet mutations, merges, releases, or deployments.

Verification

All passed locally:

  • go test ./...
  • go -C tools test ./...
  • go test -race ./cmd/tscli/create/key ./pkg/apitype ./pkg/output ./test/cli
  • go build ./... and go -C tools build ./...
  • go vet ./... and go -C tools vet ./...
  • make coverage-gaps-check (zero uncovered operations/properties)
  • make docs-generate and make docs-check
  • git diff --cached --check

Observed failing tests before implementation for the missing flag, validation, and property registry, then passing tests. Mock HTTP tests cover mixed types, large integers, exact nesting, existing flags/defaults, and actionable API permission failures; validation tests cover malformed input, namespace/type/count limits, and non-auth-key rejection. Baseline root tests also passed.

Response regressions were observed failing before each create/get/list fix, and a second failure exposed printer rounding of 9007199254740993. Passing mock regressions now verify mixed attribute types, exact large integers in JSON/YAML, preserved metadata/capability flags, list array shape and all=true, empty lists, malformed responses, and API permission errors. Model compatibility tests compare attribute-free responses with the pinned SDK. Numeric printer tests also cover nested arrays, decimal/exponent numbers, and integers larger than uint64. The response property registry test was red before registration, then green.

One-shot self-review and added-line security scan completed: no findings. No independent human review claimed. Default branch and all open PRs rechecked before publishing; the existing dependency PR is unrelated.

Copilot AI balanced review requested due to automatic review settings November 7, 2026 15:40
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-07T15:42:16.284973Z 2c8ad70 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

The request model sends an explicit expirySeconds: 0 when --expiry is omitted, bypassing the contract’s absent-property default; add omitempty and test that the property is absent.

1 open issue
What changed in this PR

Adds custom device posture attributes to auth-key creation through tscli create key --node-attributes, using a local request model without upgrading the SDK.

Changes:

  • Validates attribute names, types, and count before client initialization while preserving large integers.
  • Adds payload, validation, permission-error, and default-omission tests.
  • Refreshes the OpenAPI snapshot, coverage reports, and command documentation.
File Description
tools/​internal/​coveragegaps/​properties.go Uses the shared capability model for request coverage.
tools/​internal/​coveragegaps/​key_properties_test.go Checks node-attribute property coverage.
test/​cli/​create_key_node_attributes_test.go Tests attribute serialization and existing flags.
test/​cli/​create_key_node_attributes_error_test.go Tests permission-error reporting.
test/​cli/​create_key_flags_integration_test.go Checks default omission of node attributes.
pkg/​contract/​openapi/​tailscale-v2-openapi.yaml Adds the upstream attribute schema and permission requirement.
pkg/​contract/​openapi/​snapshot-metadata.yaml Updates snapshot timestamp and checksum.
pkg/​apitype/​key.go Defines local auth-key request and capability models.
docs/​commands/​tscli_create_key.md Documents the flag, example, and caller permissions.
coverage/​property-coverage.yaml Registers attribute payload test evidence.
coverage/​coverage-gaps.md Refreshes the readable property coverage report.
coverage/​coverage-gaps.json Refreshes machine-readable property coverage.
cmd/​tscli/​create/​key/​node_attributes.go Parses and validates attributes without numeric rounding.
cmd/​tscli/​create/​key/​node_attributes_test.go Tests boundaries and validation before client initialization.
cmd/​tscli/​create/​key/​cli.go Wires the flag into validation and authenticated requests.

Review effort: Balanced

Comment thread pkg/apitype/key.go Resolved
jaxxstorm and others added 2 commits November 7, 2026 15:54
Make ExpirySeconds optional in CreateKeyRequest.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
@jaxxstorm
jaxxstorm merged commit a7d2848 into main Nov 7, 2026
1 check passed
@jaxxstorm
jaxxstorm deleted the automation/tailscale-api-auth-key-node-attributes branch November 7, 2026 22:10
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.

2 participants