diff --git a/cmd/api_keys.go b/cmd/api_keys.go index 87b363e8..165607fa 100644 --- a/cmd/api_keys.go +++ b/cmd/api_keys.go @@ -4,6 +4,7 @@ import ( "context" "encoding/json" "fmt" + "net" "strings" "time" @@ -31,24 +32,30 @@ type APIKeysCmd struct { } type APIKeysCreateInput struct { - Name string - DaysToExpire Int64Flag - ExpiresAt string - ProjectID string - Policy string - Output string + Name string + DaysToExpire Int64Flag + ExpiresAt string + ProjectID string + ServiceAccountID string + Policy string + PolicyProvided bool + Output string } type APIKeysListInput struct { - Limit int - Offset int - Name string - Query string - Status string - IncludeDeleted bool - SortBy string - SortDirection string - Output string + Limit int + Offset int + Name string + Query string + Status string + CreatedBy string + ProjectID string + ServiceAccountID string + PrincipalType string + IncludeDeleted bool + SortBy string + SortDirection string + Output string } type APIKeysGetInput struct { @@ -66,9 +73,12 @@ type APIKeysRotateInput struct { } type APIKeysUpdateInput struct { - ID string - Name string - Output string + ID string + Name string + NameProvided bool + Policy string + PolicyProvided bool + Output string } type APIKeysDeleteInput struct { @@ -76,27 +86,78 @@ type APIKeysDeleteInput struct { SkipConfirm bool } -func parseAPIKeyPolicy(raw string) (kernel.APIKeyNewParamsPolicy, bool, error) { +func parseAPIKeyPolicy[T any](raw string) (T, error) { + var zero T trimmed := strings.TrimSpace(raw) - if trimmed == "" { - return kernel.APIKeyNewParamsPolicy{}, false, nil + if trimmed == "" || !strings.HasPrefix(trimmed, "{") { + return zero, fmt.Errorf("--policy must be a JSON object with a statements array") } - if !strings.HasPrefix(trimmed, "{") { - return kernel.APIKeyNewParamsPolicy{}, false, fmt.Errorf("--policy must be a JSON object with a statements array") + + var shape struct { + Statements []json.RawMessage `json:"statements"` } - var policy kernel.APIKeyNewParamsPolicy - if err := json.Unmarshal([]byte(trimmed), &policy); err != nil { - return kernel.APIKeyNewParamsPolicy{}, false, fmt.Errorf("--policy must be a JSON object with a statements array: %w", err) + if err := json.Unmarshal([]byte(trimmed), &shape); err != nil { + return zero, fmt.Errorf("--policy must be a JSON object with a statements array: %w", err) } - if len(policy.Statements) < 1 || len(policy.Statements) > 256 { - return kernel.APIKeyNewParamsPolicy{}, false, fmt.Errorf("--policy statements must contain between 1 and 256 entries") + if len(shape.Statements) < 1 || len(shape.Statements) > 256 { + return zero, fmt.Errorf("--policy statements must contain between 1 and 256 entries") } - for i, statement := range policy.Statements { + for i, rawStatement := range shape.Statements { + var fields map[string]json.RawMessage + if err := json.Unmarshal(rawStatement, &fields); err != nil || fields == nil { + return zero, fmt.Errorf("--policy statements[%d] must be an object", i) + } + if condition, ok := fields["condition"]; ok && strings.TrimSpace(string(condition)) == "null" { + return zero, fmt.Errorf("--policy statements[%d].condition must be an object when present", i) + } + var statement struct { + Action string `json:"action"` + Resource string `json:"resource"` + Condition *apiKeyPolicyConditionInput `json:"condition"` + } + if err := json.Unmarshal(rawStatement, &statement); err != nil { + return zero, fmt.Errorf("--policy statements[%d] must be an object: %w", i, err) + } if strings.TrimSpace(statement.Action) == "" || strings.TrimSpace(statement.Resource) == "" { - return kernel.APIKeyNewParamsPolicy{}, false, fmt.Errorf("--policy statements[%d] requires non-empty action and resource", i) + return zero, fmt.Errorf("--policy statements[%d] requires non-empty action and resource", i) + } + if statement.Condition != nil { + if err := validateAPIKeyPolicyCondition(i, *statement.Condition); err != nil { + return zero, err + } } } - return policy, true, nil + + var policy T + if err := json.Unmarshal([]byte(trimmed), &policy); err != nil { + return zero, fmt.Errorf("invalid --policy JSON: %w", err) + } + return policy, nil +} + +type apiKeyPolicyConditionInput struct { + Key string `json:"key"` + Operator string `json:"operator"` + Values []string `json:"values"` +} + +func validateAPIKeyPolicyCondition(statement int, condition apiKeyPolicyConditionInput) error { + if condition.Key != "source_ip" { + return fmt.Errorf("--policy statements[%d].condition.key must be source_ip", statement) + } + if condition.Operator != "in" { + return fmt.Errorf("--policy statements[%d].condition.operator must be in", statement) + } + if len(condition.Values) < 1 || len(condition.Values) > 16 { + return fmt.Errorf("--policy statements[%d].condition.values must contain between 1 and 16 CIDR networks", statement) + } + for i, value := range condition.Values { + ip, network, err := net.ParseCIDR(value) + if err != nil || !ip.Equal(network.IP) || (ip.To4() != nil && strings.Contains(value, ":")) { + return fmt.Errorf("--policy statements[%d].condition.values[%d] must be a canonical IPv4 or IPv6 CIDR network", statement, i) + } + } + return nil } func (c APIKeysCmd) Create(ctx context.Context, in APIKeysCreateInput) error { @@ -131,11 +192,21 @@ func (c APIKeysCmd) Create(ctx context.Context, in APIKeysCreateInput) error { if in.ProjectID != "" { params.ProjectID = kernel.String(in.ProjectID) } - policy, policySet, err := parseAPIKeyPolicy(in.Policy) - if err != nil { - return err + policyProvided := in.PolicyProvided || strings.TrimSpace(in.Policy) != "" + if in.ServiceAccountID != "" { + params.ServiceAccountID = kernel.String(in.ServiceAccountID) + if in.ProjectID == "" { + return fmt.Errorf("--service-account-id requires --project-id") + } + if !policyProvided { + return fmt.Errorf("--service-account-id requires --policy") + } } - if policySet { + if policyProvided { + policy, err := parseAPIKeyPolicy[kernel.APIKeyNewParamsPolicy](in.Policy) + if err != nil { + return err + } params.Policy = policy } @@ -177,18 +248,39 @@ func (c APIKeysCmd) List(ctx context.Context, in APIKeysListInput) error { if in.Query != "" { params.Query = kernel.String(in.Query) } + if in.CreatedBy != "" { + params.CreatedBy = kernel.String(in.CreatedBy) + } + if in.ProjectID != "" { + params.ProjectID = kernel.String(in.ProjectID) + } + if in.ServiceAccountID != "" { + params.ServiceAccountID = kernel.String(in.ServiceAccountID) + } + if in.PrincipalType != "" { + switch in.PrincipalType { + case "user": + params.PrincipalType = kernel.APIKeyListParamsPrincipalTypeUser + case "service_account": + params.PrincipalType = kernel.APIKeyListParamsPrincipalTypeServiceAccount + default: + return fmt.Errorf("invalid --principal-type value: %s (must be 'user' or 'service_account')", in.PrincipalType) + } + } // Prefer the newer --status filter; fall back to the deprecated // --include-deleted so existing scripts keep working. if in.Status != "" { switch in.Status { case "active": params.Status = kernel.APIKeyListParamsStatusActive + case "expired": + params.Status = kernel.APIKeyListParamsStatusExpired case "deleted": params.Status = kernel.APIKeyListParamsStatusDeleted case "all": params.Status = kernel.APIKeyListParamsStatusAll default: - return fmt.Errorf("invalid --status value: %s (must be 'active', 'deleted', or 'all')", in.Status) + return fmt.Errorf("invalid --status value: %s (must be 'active', 'expired', 'deleted', or 'all')", in.Status) } } else if in.IncludeDeleted { params.IncludeDeleted = kernel.Opt(true) @@ -239,7 +331,7 @@ func (c APIKeysCmd) List(ctx context.Context, in APIKeysListInput) error { // Only surface Deleted At when the filter can actually return deleted keys. showDeletedAt := in.IncludeDeleted || in.Status == "deleted" || in.Status == "all" - header := []string{"ID", "Name", "Scope", "Project", "Masked Key", "Expires At", "Last Used At", "Created At"} + header := []string{"ID", "Name", "Scope", "Principal", "Project", "Masked Key", "Expires At", "Last Used At", "Created At"} if showDeletedAt { header = append(header, "Deleted At") } @@ -249,6 +341,7 @@ func (c APIKeysCmd) List(ctx context.Context, in APIKeysListInput) error { key.ID, key.Name, formatAPIKeyScope(key), + formatAPIKeyPrincipal(key), formatAPIKeyProject(key), key.MaskedKey, formatAPIKeyExpiresAt(key), @@ -291,11 +384,28 @@ func (c APIKeysCmd) Update(ctx context.Context, in APIKeysUpdateInput) error { if err := validateJSONOutput(in.Output); err != nil { return err } - if in.Name == "" { - return fmt.Errorf("--name is required") + + nameProvided := in.NameProvided || in.Name != "" + policyProvided := in.PolicyProvided || strings.TrimSpace(in.Policy) != "" + params := kernel.APIKeyUpdateParams{} + if nameProvided { + if strings.TrimSpace(in.Name) == "" { + return fmt.Errorf("--name must not be empty") + } + params.Name = kernel.String(in.Name) + } + if policyProvided { + policy, err := parseAPIKeyPolicy[kernel.APIKeyUpdateParamsPolicy](in.Policy) + if err != nil { + return err + } + params.Policy = policy + } + if !nameProvided && !policyProvided { + return fmt.Errorf("specify at least one of --name or --policy") } - key, err := c.apiKeys.Update(ctx, in.ID, kernel.APIKeyUpdateParams{Name: in.Name}) + key, err := c.apiKeys.Update(ctx, in.ID, params) if err != nil { return util.CleanedUpSdkError{Err: err} } @@ -395,10 +505,12 @@ func renderCreatedAPIKey(key *kernel.CreatedAPIKey) { {"Name", key.Name}, {"Key", key.Key}, {"Scope", formatAPIKeyScope(key.APIKey)}, + {"Principal", formatAPIKeyPrincipal(key.APIKey)}, {"Project", formatAPIKeyProject(key.APIKey)}, {"Masked Key", key.MaskedKey}, {"Expires At", formatAPIKeyExpiresAt(key.APIKey)}, } + rows = appendAPIKeyPolicyRows(rows, key.APIKey) PrintTableNoPad(rows, true) } @@ -408,6 +520,7 @@ func renderAPIKeyDetails(key *kernel.APIKey) { {"ID", key.ID}, {"Name", key.Name}, {"Scope", formatAPIKeyScope(*key)}, + {"Principal", formatAPIKeyPrincipal(*key)}, {"Project", formatAPIKeyProject(*key)}, {"Masked Key", key.MaskedKey}, {"Created By", formatAPIKeyCreator(*key)}, @@ -415,9 +528,32 @@ func renderAPIKeyDetails(key *kernel.APIKey) { {"Last Used At", formatAPIKeyLastUsedAt(*key)}, {"Created At", util.FormatLocal(key.CreatedAt)}, } + rows = appendAPIKeyPolicyRows(rows, *key) PrintTableNoPad(rows, true) } +func appendAPIKeyPolicyRows(rows pterm.TableData, key kernel.APIKey) pterm.TableData { + for i, statement := range key.Policy.Statements { + value := statement.Action + " " + statement.Resource + if statement.JSON.Condition.Valid() { + condition := statement.Condition + value += fmt.Sprintf(" when %s %s [%s]", condition.Key, condition.Operator, strings.Join(condition.Values, ", ")) + } + rows = append(rows, []string{fmt.Sprintf("Policy %d", i+1), value}) + } + return rows +} + +func formatAPIKeyPrincipal(key kernel.APIKey) string { + if key.JSON.Principal.Valid() && key.Principal.Type != "" && key.Principal.ID != "" { + return fmt.Sprintf("%s:%s", key.Principal.Type, key.Principal.ID) + } + if key.JSON.ServiceAccountID.Valid() && key.ServiceAccountID != "" { + return "service_account:" + key.ServiceAccountID + } + return "-" +} + func formatAPIKeyProject(key kernel.APIKey) string { if key.JSON.ProjectName.Valid() && key.ProjectName != "" { return key.ProjectName @@ -470,6 +606,7 @@ func runAPIKeysCreate(cmd *cobra.Command, args []string) error { daysToExpire, _ := cmd.Flags().GetInt64("days-to-expire") expiresAt, _ := cmd.Flags().GetString("expires-at") projectID, _ := cmd.Flags().GetString("project-id") + serviceAccountID, _ := cmd.Flags().GetString("service-account-id") policy, _ := cmd.Flags().GetString("policy") output, _ := cmd.Flags().GetString("output") @@ -479,10 +616,12 @@ func runAPIKeysCreate(cmd *cobra.Command, args []string) error { Set: cmd.Flags().Changed("days-to-expire"), Value: daysToExpire, }, - ExpiresAt: expiresAt, - ProjectID: projectID, - Policy: policy, - Output: output, + ExpiresAt: expiresAt, + ProjectID: projectID, + ServiceAccountID: serviceAccountID, + Policy: policy, + PolicyProvided: cmd.Flags().Changed("policy"), + Output: output, }) } @@ -493,20 +632,28 @@ func runAPIKeysList(cmd *cobra.Command, args []string) error { name, _ := cmd.Flags().GetString("name") query, _ := cmd.Flags().GetString("query") status, _ := cmd.Flags().GetString("status") + createdBy, _ := cmd.Flags().GetString("created-by") + projectID, _ := cmd.Flags().GetString("project-id") + serviceAccountID, _ := cmd.Flags().GetString("service-account-id") + principalType, _ := cmd.Flags().GetString("principal-type") includeDeleted, _ := cmd.Flags().GetBool("include-deleted") sortBy, _ := cmd.Flags().GetString("sort-by") sortDirection, _ := cmd.Flags().GetString("sort-direction") output, _ := cmd.Flags().GetString("output") return c.List(cmd.Context(), APIKeysListInput{ - Limit: limit, - Offset: offset, - Name: name, - Query: query, - Status: status, - IncludeDeleted: includeDeleted, - SortBy: sortBy, - SortDirection: sortDirection, - Output: output, + Limit: limit, + Offset: offset, + Name: name, + Query: query, + Status: status, + CreatedBy: createdBy, + ProjectID: projectID, + ServiceAccountID: serviceAccountID, + PrincipalType: principalType, + IncludeDeleted: includeDeleted, + SortBy: sortBy, + SortDirection: sortDirection, + Output: output, }) } @@ -535,8 +682,16 @@ func runAPIKeysRotate(cmd *cobra.Command, args []string) error { func runAPIKeysUpdate(cmd *cobra.Command, args []string) error { c := getAPIKeysHandler(cmd) name, _ := cmd.Flags().GetString("name") + policy, _ := cmd.Flags().GetString("policy") output, _ := cmd.Flags().GetString("output") - return c.Update(cmd.Context(), APIKeysUpdateInput{ID: args[0], Name: name, Output: output}) + return c.Update(cmd.Context(), APIKeysUpdateInput{ + ID: args[0], + Name: name, + NameProvided: cmd.Flags().Changed("name"), + Policy: policy, + PolicyProvided: cmd.Flags().Changed("policy"), + Output: output, + }) } func runAPIKeysDelete(cmd *cobra.Command, args []string) error { @@ -556,18 +711,28 @@ var apiKeysCmd = &cobra.Command{ var apiKeysCreateCmd = &cobra.Command{ Use: "create", - Short: "Create an API key", - Long: "Create an API key.\n\nBy default the new key is org-wide. Use --project-id to create a key whose own access is scoped to that project. The global --project flag only scopes this CLI request. Use --policy to issue a least-privilege key: every action and resource not listed in its allow statements is denied.", - Args: cobra.NoArgs, - RunE: runAPIKeysCreate, + Short: "Create a personal or service-account API key", + Long: `Create a personal API key, or link a key to an organization-owned service account. + +By default the new key is org-wide. Use --project-id to scope it to a project; the +global --project flag only scopes this CLI request. Service-account keys require +organization-administrator access plus --service-account-id, --project-id, and a +non-empty --policy. + +A policy restricts the key to its listed actions and resources. Each statement may +include a source_ip condition whose values are CIDR networks. Requests from outside +those networks are rejected even if the key secret is valid.`, + Args: cobra.NoArgs, + RunE: runAPIKeysCreate, } var apiKeysListCmd = &cobra.Command{ Use: "list", Short: "List API keys", - Long: "List API keys. Last-used timestamps are accurate to within about 20 minutes; '-' means no use has been recorded since tracking began.", - Args: cobra.NoArgs, - RunE: runAPIKeysList, + Long: "List API keys. By default only non-deleted, non-expired keys are returned; use --status expired, deleted, or all for other lifecycle states. " + + "Last-used timestamps are accurate to within about 20 minutes; '-' means no use has been recorded since tracking began.", + Args: cobra.NoArgs, + RunE: runAPIKeysList, } var apiKeysGetCmd = &cobra.Command{ @@ -580,15 +745,22 @@ var apiKeysGetCmd = &cobra.Command{ var apiKeysUpdateCmd = &cobra.Command{ Use: "update ", - Short: "Update an API key", - Args: cobra.ExactArgs(1), - RunE: runAPIKeysUpdate, + Short: "Update an API key's name or replace its policy", + Long: `Update an API key without rotating its credential. + +--name renames the key. A present --policy fully replaces its current permissions, +including source_ip conditions, and applies to new requests within the authorization +cache. Requests outside allowed CIDR networks are rejected and recorded in the audit +log with the client address. Renaming requires api_keys:write; replacing +permissions requires api_keys:set_policy.`, + Args: cobra.ExactArgs(1), + RunE: runAPIKeysUpdate, } var apiKeysRotateCmd = &cobra.Command{ Use: "rotate ", Short: "Rotate an API key", - Long: "Issue a replacement API key. The rotated key keeps working for a grace period (7 days by default) so callers can migrate. Use --expire-in-days 0 to expire it immediately; browser sessions attributed to the old key then end asynchronously and unsaved profile changes are discarded. Grace-period and natural expiry do not end existing browser sessions. If immediate cleanup cannot be scheduled, the rotation is not completed.", + Long: "Issue a replacement API key. The rotated key keeps working for a grace period (7 days by default) so callers can migrate. Use --expire-in-days 0 to expire it immediately; browser sessions attributed to the old key then end asynchronously and unsaved profile changes are discarded. Grace-period and natural expiry do not end existing browser sessions. If immediate cleanup cannot be scheduled, the rotation is not completed. Service-account keys retain their service principal and policy; the rotating administrator is recorded separately for audit.", Args: cobra.ExactArgs(1), RunE: runAPIKeysRotate, } @@ -606,8 +778,9 @@ func init() { apiKeysCreateCmd.Flags().String("name", "", "API key name (required)") apiKeysCreateCmd.Flags().Int64("days-to-expire", 0, "Number of days until expiry (1-3650); omit for never; mutually exclusive with --expires-at") apiKeysCreateCmd.Flags().String("expires-at", "", "Exact future expiry time in RFC3339 format; cannot be later than the issuing credential's expiry; mutually exclusive with --days-to-expire") - apiKeysCreateCmd.Flags().String("project-id", "", "Create a project-scoped API key for this project ID; omit for org-wide") - apiKeysCreateCmd.Flags().String("policy", "", `JSON policy object, for example {"statements":[{"action":"browsers:use","resource":"projects/proj_123/browsers/*"}]}; unlisted access is denied`) + apiKeysCreateCmd.Flags().String("project-id", "", "Create a project-scoped API key for this project ID; required for service-account keys") + apiKeysCreateCmd.Flags().String("service-account-id", "", "Link the key to this organization-owned service account; requires --project-id and --policy") + apiKeysCreateCmd.Flags().String("policy", "", `JSON policy object; statements may include {"condition":{"key":"source_ip","operator":"in","values":["203.0.113.0/24"]}}; unlisted access is denied`) apiKeysCreateCmd.MarkFlagsMutuallyExclusive("days-to-expire", "expires-at") _ = apiKeysCreateCmd.MarkFlagRequired("name") @@ -616,8 +789,12 @@ func init() { apiKeysListCmd.Flags().Int("offset", 0, "Number of results to skip") apiKeysListCmd.Flags().String("name", "", "Filter by exact API key name (names are not unique, so several keys may match)") apiKeysListCmd.Flags().String("query", "", "Search API keys by name, creator, or project (identifiers and masked keys match by exact value or prefix)") - apiKeysListCmd.Flags().String("status", "", "Filter by status: 'active' (default), 'deleted', or 'all'") - apiKeysListCmd.Flags().Bool("include-deleted", false, "Deprecated: Use --status all instead. Include soft-deleted API keys in the results") + apiKeysListCmd.Flags().String("status", "", "Filter by status: active (default), expired, deleted, or all") + apiKeysListCmd.Flags().String("created-by", "", "Return only keys created by this user ID (the same person described by each key's created_by field)") + apiKeysListCmd.Flags().String("project-id", "", "Return only keys scoped to this project ID; use 'org' for keys not scoped to a project") + apiKeysListCmd.Flags().String("service-account-id", "", "Return only keys that belong to this service account") + apiKeysListCmd.Flags().String("principal-type", "", "Return only keys acting as this principal type: user or service_account") + apiKeysListCmd.Flags().Bool("include-deleted", false, "Deprecated: use --status all instead. Include soft-deleted API keys in the results") apiKeysListCmd.Flags().String("sort-by", "", "Sort by: created_at, name, expires_at, or last_used_at. Keys without an expiry sort last for expires_at; keys without recorded use sort last for last_used_at, in either direction") apiKeysListCmd.Flags().String("sort-direction", "", "Sort direction: asc or desc") @@ -625,8 +802,9 @@ func init() { apiKeysGetCmd.Flags().Bool("include-deleted", false, "Include soft-deleted API keys in the lookup") addJSONOutputFlag(apiKeysUpdateCmd) - apiKeysUpdateCmd.Flags().String("name", "", "New API key name (required)") - _ = apiKeysUpdateCmd.MarkFlagRequired("name") + apiKeysUpdateCmd.Flags().String("name", "", "New API key name; omit to leave unchanged") + apiKeysUpdateCmd.Flags().String("policy", "", "Replacement JSON policy; statements may include source_ip CIDR conditions") + apiKeysUpdateCmd.MarkFlagsOneRequired("name", "policy") addJSONOutputFlag(apiKeysRotateCmd) apiKeysRotateCmd.Flags().Int64("days-to-expire", 0, "Lifetime in days for the new key (1-3650); omit to reuse the rotated key's lifetime") diff --git a/cmd/api_keys_test.go b/cmd/api_keys_test.go index d2b25367..46de013c 100644 --- a/cmd/api_keys_test.go +++ b/cmd/api_keys_test.go @@ -57,7 +57,11 @@ func (f *FakeAPIKeysService) Update(ctx context.Context, id string, body kernel. if f.UpdateFunc != nil { return f.UpdateFunc(ctx, id, body, opts...) } - return apiKeyFromJSON(`{"id":"` + id + `","name":"` + body.Name + `","masked_key":"sk_...test","created_at":"2026-05-27T12:00:00Z","created_by":{"id":"user_123","email":"dev@example.com","name":"Dev"},"expires_at":null,"project_id":null,"project_name":null}`), nil + name := "default" + if body.Name.Valid() { + name = body.Name.Value + } + return apiKeyFromJSON(`{"id":"` + id + `","name":"` + name + `","masked_key":"sk_...test","created_at":"2026-05-27T12:00:00Z","created_by":{"id":"user_123","email":"dev@example.com","name":"Dev"},"expires_at":null,"project_id":null,"project_name":null}`), nil } func (f *FakeAPIKeysService) List(ctx context.Context, query kernel.APIKeyListParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.APIKey], error) { @@ -155,6 +159,41 @@ func TestAPIKeysCreateSupportsExactExpiryAndPolicy(t *testing.T) { require.NoError(t, err) } +func TestAPIKeysCreateSupportsServiceAccountAndSourceIPCondition(t *testing.T) { + capturePtermOutput(t) + fake := &FakeAPIKeysService{ + NewFunc: func(ctx context.Context, body kernel.APIKeyNewParams, opts ...option.RequestOption) (*kernel.CreatedAPIKey, error) { + require.True(t, body.ServiceAccountID.Valid()) + assert.Equal(t, "sa_123", body.ServiceAccountID.Value) + require.True(t, body.ProjectID.Valid()) + require.Len(t, body.Policy.Statements, 1) + raw, err := json.Marshal(body) + require.NoError(t, err) + assert.JSONEq(t, `{"name":"automation","project_id":"proj_123","service_account_id":"sa_123","policy":{"statements":[{"action":"browsers:use","resource":"projects/proj_123/browsers/*","condition":{"key":"source_ip","operator":"in","values":["203.0.113.0/24"]}}]}}`, string(raw)) + return createdAPIKeyFromJSON(`{"id":"key_123","name":"automation","key":"sk_live_123","masked_key":"sk_...123","created_at":"2026-05-27T12:00:00Z","created_by":{"id":"user_123"},"expires_at":null,"project_id":"proj_123","service_account_id":"sa_123"}`), nil + }, + } + c := APIKeysCmd{apiKeys: fake} + + err := c.Create(context.Background(), APIKeysCreateInput{ + Name: "automation", + ProjectID: "proj_123", + ServiceAccountID: "sa_123", + Policy: `{"statements":[{"action":"browsers:use","resource":"projects/proj_123/browsers/*","condition":{"key":"source_ip","operator":"in","values":["203.0.113.0/24"]}}]}`, + }) + require.NoError(t, err) +} + +func TestAPIKeysCreateServiceAccountRequiresProjectAndPolicy(t *testing.T) { + c := APIKeysCmd{apiKeys: &FakeAPIKeysService{}} + + err := c.Create(context.Background(), APIKeysCreateInput{Name: "automation", ServiceAccountID: "sa_123"}) + require.ErrorContains(t, err, "--project-id") + + err = c.Create(context.Background(), APIKeysCreateInput{Name: "automation", ServiceAccountID: "sa_123", ProjectID: "proj_123"}) + require.ErrorContains(t, err, "--policy") +} + func TestAPIKeysCreateRejectsInvalidExpiryAndPolicy(t *testing.T) { called := false fake := &FakeAPIKeysService{NewFunc: func(ctx context.Context, body kernel.APIKeyNewParams, opts ...option.RequestOption) (*kernel.CreatedAPIKey, error) { @@ -173,6 +212,8 @@ func TestAPIKeysCreateRejectsInvalidExpiryAndPolicy(t *testing.T) { {"invalid policy json", APIKeysCreateInput{Name: "ci", Policy: "[]"}, "JSON object"}, {"empty statements", APIKeysCreateInput{Name: "ci", Policy: `{"statements":[]}`}, "between 1 and 256"}, {"empty statement field", APIKeysCreateInput{Name: "ci", Policy: `{"statements":[{"action":"","resource":"projects/*"}]}`}, "non-empty action and resource"}, + {"invalid condition key", APIKeysCreateInput{Name: "ci", Policy: `{"statements":[{"action":"browsers:use","resource":"*","condition":{"key":"other","operator":"in","values":["203.0.113.0/24"]}}]}`}, "must be source_ip"}, + {"invalid condition network", APIKeysCreateInput{Name: "ci", Policy: `{"statements":[{"action":"browsers:use","resource":"*","condition":{"key":"source_ip","operator":"in","values":["203.0.113.7/24"]}}]}`}, "canonical"}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { @@ -292,16 +333,72 @@ func TestAPIKeysListSupportsLastUsedAtSort(t *testing.T) { require.NoError(t, err) } +func TestAPIKeysListMapsIdentityFiltersAndExpiredStatus(t *testing.T) { + capturePtermOutput(t) + fake := &FakeAPIKeysService{ + ListFunc: func(ctx context.Context, query kernel.APIKeyListParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.APIKey], error) { + require.True(t, query.CreatedBy.Valid()) + assert.Equal(t, "user_123", query.CreatedBy.Value) + require.True(t, query.ProjectID.Valid()) + assert.Equal(t, "org", query.ProjectID.Value) + require.True(t, query.ServiceAccountID.Valid()) + assert.Equal(t, "sa_123", query.ServiceAccountID.Value) + assert.Equal(t, kernel.APIKeyListParamsPrincipalTypeServiceAccount, query.PrincipalType) + assert.Equal(t, kernel.APIKeyListParamsStatusExpired, query.Status) + return &pagination.OffsetPagination[kernel.APIKey]{Items: []kernel.APIKey{}}, nil + }, + } + c := APIKeysCmd{apiKeys: fake} + + err := c.List(context.Background(), APIKeysListInput{ + CreatedBy: "user_123", + ProjectID: "org", + ServiceAccountID: "sa_123", + PrincipalType: "service_account", + Status: "expired", + }) + require.NoError(t, err) +} + +func TestAPIKeysListRejectsUnknownPrincipalType(t *testing.T) { + c := APIKeysCmd{apiKeys: &FakeAPIKeysService{}} + err := c.List(context.Background(), APIKeysListInput{PrincipalType: "robot"}) + require.Error(t, err) + assert.Contains(t, err.Error(), "user") + assert.Contains(t, err.Error(), "service_account") +} + func TestFormatAPIKeyLastUsedAtHandlesUnrecordedUse(t *testing.T) { key := apiKeyFromJSON(`{"last_used_at":null}`) assert.Equal(t, "-", formatAPIKeyLastUsedAt(*key)) } -func TestAPIKeysUpdateRequiresName(t *testing.T) { +func TestAPIKeysUpdateRequiresAChange(t *testing.T) { c := APIKeysCmd{apiKeys: &FakeAPIKeysService{}} err := c.Update(context.Background(), APIKeysUpdateInput{ID: "key_123"}) require.Error(t, err) - assert.Contains(t, err.Error(), "--name is required") + assert.Contains(t, err.Error(), "at least one of --name or --policy") +} + +func TestAPIKeysUpdateCanReplacePolicyWithoutRenaming(t *testing.T) { + capturePtermOutput(t) + fake := &FakeAPIKeysService{ + UpdateFunc: func(ctx context.Context, id string, body kernel.APIKeyUpdateParams, opts ...option.RequestOption) (*kernel.APIKey, error) { + assert.False(t, body.Name.Valid()) + require.Len(t, body.Policy.Statements, 1) + raw, err := json.Marshal(body) + require.NoError(t, err) + assert.Contains(t, string(raw), `"condition":{"key":"source_ip","operator":"in","values":["2001:db8::/32"]}`) + return apiKeyFromJSON(`{"id":"key_123","name":"ci","masked_key":"sk_...123","created_at":"2026-05-27T12:00:00Z","created_by":{"id":"user_123"},"expires_at":null,"project_id":null,"project_name":null}`), nil + }, + } + c := APIKeysCmd{apiKeys: fake} + + err := c.Update(context.Background(), APIKeysUpdateInput{ + ID: "key_123", + Policy: `{"statements":[{"action":"vaults:read","resource":"projects/proj_123/vaults/*","condition":{"key":"source_ip","operator":"in","values":["2001:db8::/32"]}}]}`, + }) + require.NoError(t, err) } func TestAPIKeysUpdatePrintsTerseSuccess(t *testing.T) { @@ -309,7 +406,8 @@ func TestAPIKeysUpdatePrintsTerseSuccess(t *testing.T) { fake := &FakeAPIKeysService{ UpdateFunc: func(ctx context.Context, id string, body kernel.APIKeyUpdateParams, opts ...option.RequestOption) (*kernel.APIKey, error) { assert.Equal(t, "key_123", id) - assert.Equal(t, "renamed", body.Name) + require.True(t, body.Name.Valid()) + assert.Equal(t, "renamed", body.Name.Value) return apiKeyFromJSON(`{"id":"key_123","name":"renamed","masked_key":"sk_...123","created_at":"2026-05-27T12:00:00Z","created_by":{"id":"user_123","email":"dev@example.com","name":"Dev"},"expires_at":null,"project_id":null,"project_name":null}`), nil }, } diff --git a/cmd/auth_connections.go b/cmd/auth_connections.go index 221abe53..9c4992ee 100644 --- a/cmd/auth_connections.go +++ b/cmd/auth_connections.go @@ -53,6 +53,7 @@ type AuthConnectionCreateInput struct { Region string Locale string Stealth BoolFlag + CaptchaSolver BoolFlag SaveCredentials bool NoSaveCredentials bool HealthCheckInterval int @@ -95,6 +96,7 @@ type AuthConnectionUpdateInput struct { LocaleSet bool ClearLocale bool Stealth BoolFlag + CaptchaSolver BoolFlag SaveCredentials BoolFlag HealthCheckInterval int HealthCheckIntervalSet bool @@ -130,6 +132,7 @@ type AuthConnectionLoginInput struct { ProxyMode string Region string Stealth BoolFlag + CaptchaSolver BoolFlag RecordSession BoolFlag SkillMode string Telemetry string @@ -183,6 +186,9 @@ func (c AuthConnectionCmd) Create(ctx context.Context, in AuthConnectionCreateIn if in.ProfileName == "" { return fmt.Errorf("--profile-name is required") } + if err := validateStealthCaptchaFlags(in.Stealth, in.CaptchaSolver); err != nil { + return err + } params := kernel.AuthConnectionNewParams{ ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{ @@ -245,6 +251,9 @@ func (c AuthConnectionCmd) Create(ctx context.Context, in AuthConnectionCreateIn if in.Stealth.Set { params.ManagedAuthCreateRequest.Browser.Stealth = kernel.Opt(in.Stealth.Value) } + if in.CaptchaSolver.Set { + params.ManagedAuthCreateRequest.Browser.CaptchaSolver = browserCaptchaSolverParam(in.CaptchaSolver.Value) + } if in.Locale != "" { params.ManagedAuthCreateRequest.Browser.Location.Locale = kernel.Opt(in.Locale) } @@ -338,7 +347,10 @@ func managedAuthBrowserRows(cfg kernel.ManagedAuthBrowserConfig) pterm.TableData } // Stealth defaults to true when omitted, so only report what the API sent. if cfg.JSON.Stealth.Valid() { - rows = append(rows, []string{"Browser Stealth", fmt.Sprintf("%t", cfg.Stealth)}) + rows = append(rows, []string{"Browser Stealth (deprecated)", fmt.Sprintf("%t", cfg.Stealth)}) + } + if cfg.JSON.CaptchaSolver.Valid() { + rows = append(rows, []string{"Browser CAPTCHA Solver", fmt.Sprintf("%t", cfg.CaptchaSolver.Enabled)}) } if cfg.Telemetry.Enabled || len(telemetryEnabledCategories(kernel.BrowserTelemetryConfig{Browser: cfg.Telemetry.Browser})) > 0 { rows = append(rows, []string{"Browser Telemetry", formatManagedAuthTelemetry(cfg.Telemetry)}) @@ -350,6 +362,9 @@ func (c AuthConnectionCmd) Update(ctx context.Context, in AuthConnectionUpdateIn if err := validateJSONOutput(in.Output); err != nil { return err } + if err := validateStealthCaptchaFlags(in.Stealth, in.CaptchaSolver); err != nil { + return err + } params := kernel.AuthConnectionUpdateParams{ ManagedAuthUpdateRequest: kernel.ManagedAuthUpdateRequestParam{}, @@ -411,7 +426,7 @@ func (c AuthConnectionCmd) Update(ctx context.Context, in AuthConnectionUpdateIn } // A proxy is selected by ID or name, so an empty value is not a way to clear it: - // dropping back to the connection's stealth-derived egress is a mode change. + // dropping back to the connection's default egress is a mode change. if (in.ProxyIDSet && in.ProxyID == "") || (in.ProxyNameSet && in.ProxyName == "") { return fmt.Errorf("proxy selection requires a non-empty value; use --proxy-mode=default to drop the selected proxy, or --proxy-mode=direct for direct egress") } @@ -439,6 +454,10 @@ func (c AuthConnectionCmd) Update(ctx context.Context, in AuthConnectionUpdateIn params.ManagedAuthUpdateRequest.Browser.Stealth = kernel.Opt(in.Stealth.Value) hasChanges = true } + if in.CaptchaSolver.Set { + params.ManagedAuthUpdateRequest.Browser.CaptchaSolver = browserCaptchaSolverParam(in.CaptchaSolver.Value) + hasChanges = true + } if in.LocaleSet && in.ClearLocale { return fmt.Errorf("cannot specify both --locale and --clear-locale") } @@ -862,6 +881,9 @@ func (c AuthConnectionCmd) Login(ctx context.Context, in AuthConnectionLoginInpu if err := validateJSONOutput(in.Output); err != nil { return err } + if err := validateStealthCaptchaFlags(in.Stealth, in.CaptchaSolver); err != nil { + return err + } params := kernel.AuthConnectionLoginParams{} sel := proxySelection{ID: in.ProxyID, Name: in.ProxyName, Mode: in.ProxyMode} @@ -884,6 +906,9 @@ func (c AuthConnectionCmd) Login(ctx context.Context, in AuthConnectionLoginInpu if in.Stealth.Set { params.Browser.Stealth = kernel.Opt(in.Stealth.Value) } + if in.CaptchaSolver.Set { + params.Browser.CaptchaSolver = browserCaptchaSolverParam(in.CaptchaSolver.Value) + } if in.RecordSession.Set { params.RecordSession = kernel.Opt(in.RecordSession.Value) @@ -1406,10 +1431,11 @@ func init() { authConnectionsCreateCmd.Flags().Bool("credential-auto", false, "Lookup by domain from the specified provider (defaults to true when --credential-provider is set without --credential-path)") authConnectionsCreateCmd.Flags().String("proxy-id", "", "Proxy ID to use for this connection's browser sessions (mutually exclusive with --proxy-name and --proxy-mode)") authConnectionsCreateCmd.Flags().String("proxy-name", "", "Proxy name to use for this connection's browser sessions (mutually exclusive with --proxy-id and --proxy-mode)") - authConnectionsCreateCmd.Flags().String("proxy-mode", "", "Proxy egress mode instead of a selected proxy: 'direct' for no proxy regardless of stealth, or 'default' for the stealth-derived default") + authConnectionsCreateCmd.Flags().String("proxy-mode", "", "Proxy egress mode instead of a selected proxy: 'direct' for no proxy, or 'default' for Kernel's default stealth proxy when CAPTCHA solving is enabled and direct egress otherwise") authConnectionsCreateCmd.Flags().String("region", "", "Geographic region for browser sessions: 'us-east', 'us-west', 'eu-west', or 'ap-southeast'. Defaults to us-east") authConnectionsCreateCmd.Flags().String("locale", "", "Browser locale for login, reauthentication, and health-check sessions (canonical BCP 47, e.g. sv-SE); omit to use the browser region's default") - authConnectionsCreateCmd.Flags().Bool("stealth", true, "Run this connection's browser sessions in stealth mode; use --stealth=false to disable") + authConnectionsCreateCmd.Flags().Bool("stealth", false, "Deprecated compatibility mode: enable CAPTCHA solving and Kernel's default stealth proxy together. If neither this nor --captcha-solver is set, the API keeps the legacy stealth default; prefer explicit --captcha-solver and --proxy-mode") + authConnectionsCreateCmd.Flags().Bool("captcha-solver", false, "Enable automatic CAPTCHA solving for login, reauthentication, and health-check sessions; does not change proxy egress") authConnectionsCreateCmd.Flags().Bool("no-save-credentials", false, "Disable saving credentials after successful login") authConnectionsCreateCmd.Flags().Int("health-check-interval", 0, "Interval in seconds between health checks. Defaults to 3600 or your plan minimum, whichever is larger. The maximum is 86400; the minimum depends on your plan (Enterprise 300, Startup 1200, Hobbyist 3600, Free 21600)") authConnectionsCreateCmd.Flags().Bool("no-health-checks", false, "Disable periodic health checks (enabled by default)") @@ -1437,11 +1463,12 @@ func init() { authConnectionsUpdateCmd.Flags().Bool("credential-auto", false, "Lookup by domain from the specified provider") authConnectionsUpdateCmd.Flags().String("proxy-id", "", "Proxy ID to use for future browser sessions (mutually exclusive with --proxy-name and --proxy-mode)") authConnectionsUpdateCmd.Flags().String("proxy-name", "", "Proxy name to use for future browser sessions (mutually exclusive with --proxy-id and --proxy-mode)") - authConnectionsUpdateCmd.Flags().String("proxy-mode", "", "Proxy egress mode instead of a selected proxy: 'direct' for no proxy regardless of stealth, or 'default' to drop a selected proxy and use the stealth-derived default") + authConnectionsUpdateCmd.Flags().String("proxy-mode", "", "Proxy egress mode instead of a selected proxy: 'direct' for no proxy, or 'default' to drop a selected proxy and use Kernel's default stealth proxy when CAPTCHA solving is enabled and direct egress otherwise") authConnectionsUpdateCmd.Flags().String("region", "", "Geographic region for future browser sessions: 'us-east', 'us-west', 'eu-west', or 'ap-southeast'") authConnectionsUpdateCmd.Flags().String("locale", "", "Set the browser locale for future login, reauthentication, and health-check sessions (canonical BCP 47, e.g. sv-SE); omit to leave it unchanged (mutually exclusive with --clear-locale)") authConnectionsUpdateCmd.Flags().Bool("clear-locale", false, "Clear the browser locale override so future sessions use the browser region's default") - authConnectionsUpdateCmd.Flags().Bool("stealth", true, "Set whether future browser sessions run in stealth mode; use --stealth=false to disable") + authConnectionsUpdateCmd.Flags().Bool("stealth", false, "Deprecated compatibility mode: enable CAPTCHA solving and Kernel's default stealth proxy together; omit to keep the current setting and prefer --captcha-solver with --proxy-mode") + authConnectionsUpdateCmd.Flags().Bool("captcha-solver", false, "Set automatic CAPTCHA solving for future sessions: enabling keeps direct egress direct; disabling a connection on default stealth egress moves it to direct; selected proxies are unchanged") authConnectionsUpdateCmd.Flags().Bool("save-credentials", false, "Enable saving credentials after successful login") authConnectionsUpdateCmd.Flags().Bool("no-save-credentials", false, "Disable saving credentials after successful login") authConnectionsUpdateCmd.Flags().Int("health-check-interval", 0, "Interval in seconds between health checks. The maximum is 86400; the minimum depends on your plan (Enterprise 300, Startup 1200, Hobbyist 3600, Free 21600)") @@ -1476,9 +1503,10 @@ func init() { addJSONOutputFlag(authConnectionsLoginCmd) authConnectionsLoginCmd.Flags().String("proxy-id", "", "Proxy ID to use for this login (mutually exclusive with --proxy-name and --proxy-mode)") authConnectionsLoginCmd.Flags().String("proxy-name", "", "Proxy name to use for this login (mutually exclusive with --proxy-id and --proxy-mode)") - authConnectionsLoginCmd.Flags().String("proxy-mode", "", "Proxy egress mode for this login instead of a selected proxy: 'direct' for no proxy regardless of stealth, or 'default' for the stealth-derived default") + authConnectionsLoginCmd.Flags().String("proxy-mode", "", "Proxy egress mode for this login instead of a selected proxy: 'direct' for no proxy, or 'default' for Kernel's default stealth proxy when CAPTCHA solving is enabled and direct egress otherwise") authConnectionsLoginCmd.Flags().String("region", "", "Geographic region override for this login: 'us-east', 'us-west', 'eu-west', or 'ap-southeast'") - authConnectionsLoginCmd.Flags().Bool("stealth", true, "Override stealth mode for this login's browser session; use --stealth=false to disable") + authConnectionsLoginCmd.Flags().Bool("stealth", false, "Deprecated compatibility override: enable CAPTCHA solving and Kernel's default stealth proxy together; omit to inherit and prefer --captcha-solver with --proxy-mode") + authConnectionsLoginCmd.Flags().Bool("captcha-solver", false, "Override automatic CAPTCHA solving for this login; omit to inherit it. Enabling does not select a proxy; disabling inherited default stealth egress uses direct egress") authConnectionsLoginCmd.Flags().Bool("record-session", false, "Override whether this login's browser session is recorded; use --record-session=false to disable") authConnectionsLoginCmd.Flags().String("skill-mode", "", "Whether this login reads and writes learned domain skills: 'enabled' (default) or 'disabled'. Automatic reauths inherit the selected mode until a later accepted login sets enabled or omits the flag") authConnectionsLoginCmd.Flags().String("telemetry", "", "Telemetry override for this login only, merged onto the connection's config: --telemetry=all, --telemetry=off, or --telemetry=console,network") @@ -1562,6 +1590,7 @@ func runAuthConnectionsCreate(cmd *cobra.Command, args []string) error { Region: region, Locale: locale, Stealth: readBoolFlag(cmd.Flags(), "stealth"), + CaptchaSolver: readBoolFlag(cmd.Flags(), "captcha-solver"), NoSaveCredentials: noSaveCredentials, HealthCheckInterval: healthCheckInterval, NoHealthChecks: noHealthChecks, @@ -1659,6 +1688,7 @@ func runAuthConnectionsUpdate(cmd *cobra.Command, args []string) error { LocaleSet: cmd.Flags().Changed("locale"), ClearLocale: clearLocale, Stealth: readBoolFlag(cmd.Flags(), "stealth"), + CaptchaSolver: readBoolFlag(cmd.Flags(), "captcha-solver"), SaveCredentials: saveCredentialsFlag, HealthCheckInterval: healthCheckInterval, HealthCheckIntervalSet: cmd.Flags().Changed("health-check-interval"), @@ -1729,6 +1759,7 @@ func runAuthConnectionsLogin(cmd *cobra.Command, args []string) error { ProxyMode: proxyMode, Region: region, Stealth: readBoolFlag(cmd.Flags(), "stealth"), + CaptchaSolver: readBoolFlag(cmd.Flags(), "captcha-solver"), RecordSession: readBoolFlag(cmd.Flags(), "record-session"), SkillMode: skillMode, Telemetry: telemetry, diff --git a/cmd/auth_connections_test.go b/cmd/auth_connections_test.go index ad07b29c..73dde0bb 100644 --- a/cmd/auth_connections_test.go +++ b/cmd/auth_connections_test.go @@ -712,6 +712,16 @@ func TestManagedAuthBrowserRows_IncludesRegionAndLocale(t *testing.T) { assert.Contains(t, rows, []string{"Browser Locale", "sv-SE"}) } +func TestManagedAuthBrowserRows_CaptchaSolverOnlyWhenReturned(t *testing.T) { + var omitted, enabled kernel.ManagedAuthBrowserConfig + require.NoError(t, json.Unmarshal([]byte(`{"region":"us-east"}`), &omitted)) + require.NoError(t, json.Unmarshal([]byte(`{"captcha_solver":{"enabled":true}}`), &enabled)) + for _, row := range managedAuthBrowserRows(omitted) { + assert.NotEqual(t, "Browser CAPTCHA Solver", row[0]) + } + assert.Contains(t, managedAuthBrowserRows(enabled), []string{"Browser CAPTCHA Solver", "true"}) +} + // --credential-auto should still be honored (it was a no-op redundant flag // before the default changed, but callers may pass it for clarity). func TestAuthConnectionsCreate_ProviderWithExplicitAuto_SetsAuto(t *testing.T) { @@ -1106,8 +1116,8 @@ func TestCreate_TelemetryOff(t *testing.T) { assert.False(t, tel.Enabled.Value) } -// Proxy and stealth are carried by the connection's browser config, which the -// API applies to its login, reauth, and health-check sessions. +// Proxy, CAPTCHA solving, and legacy stealth are carried by the connection's +// browser config, which the API applies to login, reauth, and health-check sessions. func TestCreate_BrowserConfig(t *testing.T) { capturePtermOutput(t) var captured kernel.AuthConnectionNewParams @@ -1119,16 +1129,60 @@ func TestCreate_BrowserConfig(t *testing.T) { } c := AuthConnectionCmd{svc: fake} require.NoError(t, c.Create(context.Background(), AuthConnectionCreateInput{ - Domain: "example.com", - ProfileName: "prof", - ProxyName: "my-proxy", - Stealth: BoolFlag{Set: true, Value: false}, + Domain: "example.com", + ProfileName: "prof", + ProxyName: "my-proxy", + Stealth: BoolFlag{Set: true, Value: false}, + CaptchaSolver: BoolFlag{Set: true, Value: true}, })) browser := captured.ManagedAuthCreateRequest.Browser assert.Equal(t, "my-proxy", browser.Proxy.Name.Value) require.True(t, browser.Stealth.Valid()) assert.False(t, browser.Stealth.Value) + raw, err := json.Marshal(captured) + require.NoError(t, err) + assert.Contains(t, string(raw), `"captcha_solver":{"enabled":true}`) +} + +func TestUpdateAndLogin_CaptchaSolver(t *testing.T) { + capturePtermOutput(t) + var updated kernel.AuthConnectionUpdateParams + var loggedIn kernel.AuthConnectionLoginParams + fake := &FakeAuthConnectionService{ + UpdateFunc: func(ctx context.Context, id string, body kernel.AuthConnectionUpdateParams, opts ...option.RequestOption) (*kernel.ManagedAuth, error) { + updated = body + return &kernel.ManagedAuth{ID: id}, nil + }, + LoginFunc: func(ctx context.Context, id string, body kernel.AuthConnectionLoginParams, opts ...option.RequestOption) (*kernel.LoginResponse, error) { + loggedIn = body + return &kernel.LoginResponse{ID: id}, nil + }, + } + c := AuthConnectionCmd{svc: fake} + + require.NoError(t, c.Update(context.Background(), AuthConnectionUpdateInput{ + ID: "auth_1", + CaptchaSolver: BoolFlag{Set: true, Value: false}, + })) + updatedJSON, err := json.Marshal(updated) + require.NoError(t, err) + assert.Contains(t, string(updatedJSON), `"captcha_solver":{"enabled":false}`) + + require.NoError(t, c.Login(context.Background(), AuthConnectionLoginInput{ + ID: "auth_1", + CaptchaSolver: BoolFlag{Set: true, Value: true}, + })) + loginJSON, err := json.Marshal(loggedIn) + require.NoError(t, err) + assert.Contains(t, string(loginJSON), `"captcha_solver":{"enabled":true}`) + + err = c.Login(context.Background(), AuthConnectionLoginInput{ + ID: "auth_1", + Stealth: BoolFlag{Set: true, Value: true}, + CaptchaSolver: BoolFlag{Set: true, Value: false}, + }) + require.ErrorContains(t, err, "--stealth=true") } // Region is part of the connection's browser config: create sets it, update diff --git a/cmd/auth_context.go b/cmd/auth_context.go index 9019c923..ec29f2b6 100644 --- a/cmd/auth_context.go +++ b/cmd/auth_context.go @@ -3,6 +3,7 @@ package cmd import ( "context" "fmt" + "strings" "github.com/kernel/cli/pkg/util" "github.com/kernel/kernel-go-sdk" @@ -66,9 +67,28 @@ func renderAuthContext(authCtx *kernel.AuthContext) { {"Credential Scope", formatAuthContextScope(authCtx.Authorization.CredentialScope.ProjectID)}, {"Effective Scope", formatAuthContextScope(authCtx.Authorization.EffectiveScope.ProjectID)}, } + if authCtx.JSON.WorkloadIdentity.Valid() { + rows = append(rows, + []string{"Workload Issuer ID", authCtx.WorkloadIdentity.IssuerID}, + []string{"Federation Rule ID", authCtx.WorkloadIdentity.FederationRuleID}, + []string{"External Subject Digest", authCtx.WorkloadIdentity.ExternalSubjectDigest}, + ) + } + for i, statement := range authCtx.Authorization.EffectivePolicy.Statements { + rows = append(rows, []string{fmt.Sprintf("Effective Policy %d", i+1), formatAuthContextPolicyStatement(statement)}) + } PrintTableNoPad(rows, true) } +func formatAuthContextPolicyStatement(statement kernel.AuthContextAuthorizationEffectivePolicyStatement) string { + value := statement.Action + " " + statement.Resource + if statement.JSON.Condition.Valid() { + condition := statement.Condition + value += fmt.Sprintf(" when %s %s [%s]", condition.Key, condition.Operator, strings.Join(condition.Values, ", ")) + } + return value +} + func formatAuthContextOptional(value string) string { if value == "" { return "-" @@ -91,7 +111,9 @@ var authContextCmd = &cobra.Command{ Long: `Show the identity and authorization context resolved for requests made with the current credentials. Displays the authenticated principal, organization, credential scope, and effective request scope. -Credential secrets are never returned.`, +For service-account credentials, it also shows the effective policy and sanitized workload-identity +issuer, federation-rule, and external-subject digest metadata. Assertions and credential secrets are +never returned.`, Args: cobra.NoArgs, RunE: runAuthContext, } diff --git a/cmd/auth_context_test.go b/cmd/auth_context_test.go index aa806d3c..040b340a 100644 --- a/cmd/auth_context_test.go +++ b/cmd/auth_context_test.go @@ -62,6 +62,43 @@ func TestAuthContextGet_RendersContext(t *testing.T) { assert.Contains(t, out, "proj_789") } +func TestAuthContextGet_RendersServiceAccountPolicyAndWorkloadIdentity(t *testing.T) { + buf := capturePtermOutput(t) + raw := `{ + "principal": {"id": "sa_123", "type": "service_account"}, + "organization": {"id": "org_456"}, + "authentication": {"credential_id": "key_123", "method": "api_key", "source": "workload_identity"}, + "authorization": { + "credential_scope": {"project_id": "proj_789"}, + "effective_scope": {"project_id": "proj_789"}, + "effective_policy": {"statements": [{ + "action": "browsers:use", + "resource": "projects/proj_789/browsers/*", + "condition": {"key": "source_ip", "operator": "in", "values": ["203.0.113.0/24"]} + }]} + }, + "workload_identity": { + "issuer_id": "wii_123", + "federation_rule_id": "wifr_123", + "external_subject_digest": "sha256:abcd" + } + }` + authCtx := &kernel.AuthContext{} + assert.NoError(t, authCtx.UnmarshalJSON([]byte(raw))) + c := AuthContextCmd{svc: &FakeAuthContextService{GetFunc: func(ctx context.Context, opts ...option.RequestOption) (*kernel.AuthContext, error) { + return authCtx, nil + }}} + + assert.NoError(t, c.Get(context.Background(), AuthContextGetInput{})) + out := buf.String() + assert.Contains(t, out, "service_account") + assert.Contains(t, out, "wii_123") + assert.Contains(t, out, "wifr_123") + assert.Contains(t, out, "sha256:abcd") + assert.Contains(t, out, "browsers:use") + assert.Contains(t, out, "203.0.113.0/24") +} + func TestAuthContextGet_NullFieldsRenderPlaceholders(t *testing.T) { buf := capturePtermOutput(t) fake := &FakeAuthContextService{ diff --git a/cmd/browser_pools.go b/cmd/browser_pools.go index e0aad5ce..85f837e1 100644 --- a/cmd/browser_pools.go +++ b/cmd/browser_pools.go @@ -149,6 +149,7 @@ type BrowserPoolsCreateInput struct { FillRate int64 TimeoutSeconds int64 Stealth BoolFlag + CaptchaSolver BoolFlag Headless BoolFlag Kiosk BoolFlag Memory string @@ -179,6 +180,9 @@ func (c BrowserPoolsCmd) Create(ctx context.Context, in BrowserPoolsCreateInput) if err := validateStartURLFlag(in.StartURL); err != nil { return err } + if err := validateStealthCaptchaFlags(in.Stealth, in.CaptchaSolver); err != nil { + return err + } params := kernel.BrowserPoolNewParams{ Size: in.Size, @@ -196,6 +200,9 @@ func (c BrowserPoolsCmd) Create(ctx context.Context, in BrowserPoolsCreateInput) if in.Stealth.Set { params.Stealth = kernel.Bool(in.Stealth.Value) } + if in.CaptchaSolver.Set { + params.CaptchaSolver = browserCaptchaSolverParam(in.CaptchaSolver.Value) + } if in.Headless.Set { params.Headless = kernel.Bool(in.Headless.Value) } @@ -333,6 +340,10 @@ func (c BrowserPoolsCmd) Get(ctx context.Context, in BrowserPoolsGetInput) error } cfg := pool.BrowserPoolConfig + captchaSolver := "-" + if cfg.JSON.CaptchaSolver.Valid() { + captchaSolver = fmt.Sprintf("%t", cfg.CaptchaSolver.Enabled) + } rows := pterm.TableData{ {"Property", "Value"}, @@ -346,7 +357,8 @@ func (c BrowserPoolsCmd) Get(ctx context.Context, in BrowserPoolsGetInput) error {"Fill Rate", formatFillRate(cfg.FillRatePerMinute)}, {"Timeout", fmt.Sprintf("%d seconds", cfg.TimeoutSeconds)}, {"Headless", fmt.Sprintf("%t", cfg.Headless)}, - {"Stealth", fmt.Sprintf("%t", cfg.Stealth)}, + {"Stealth (deprecated)", fmt.Sprintf("%t", cfg.Stealth)}, + {"CAPTCHA Solver", captchaSolver}, {"Kiosk Mode", fmt.Sprintf("%t", cfg.KioskMode)}, {"Memory", util.OrDash(string(cfg.Memory))}, {"Refresh On Profile Update", fmt.Sprintf("%t", cfg.RefreshOnProfileUpdate)}, @@ -373,6 +385,7 @@ type BrowserPoolsUpdateInput struct { FillRate Int64Flag TimeoutSeconds int64 Stealth BoolFlag + CaptchaSolver BoolFlag Headless BoolFlag Kiosk BoolFlag Memory string @@ -465,6 +478,9 @@ func (c BrowserPoolsCmd) Update(ctx context.Context, in BrowserPoolsUpdateInput) if err := validateBrowserPoolUpdateInput(in); err != nil { return err } + if err := validateStealthCaptchaFlags(in.Stealth, in.CaptchaSolver); err != nil { + return err + } allowedHosts, err := normalizeAllowedHosts(in.AllowedHosts, in.AllowedHostsProvided, "use --clear-allowed-hosts to remove the pool's allowlist") if err != nil { return err @@ -494,6 +510,9 @@ func (c BrowserPoolsCmd) Update(ctx context.Context, in BrowserPoolsUpdateInput) if in.Stealth.Set { params.Stealth = kernel.Bool(in.Stealth.Value) } + if in.CaptchaSolver.Set { + params.CaptchaSolver = browserCaptchaSolverParam(in.CaptchaSolver.Value) + } if in.Headless.Set { params.Headless = kernel.Bool(in.Headless.Value) } @@ -912,7 +931,8 @@ func init() { _ = browserPoolsCreateCmd.MarkFlagRequired("size") browserPoolsCreateCmd.Flags().Int64("fill-rate", 0, "Fill rate per minute") browserPoolsCreateCmd.Flags().Int64("timeout", 0, "Idle timeout in seconds") - browserPoolsCreateCmd.Flags().Bool("stealth", false, "Enable stealth mode") + browserPoolsCreateCmd.Flags().Bool("stealth", false, "Deprecated compatibility mode: enable CAPTCHA solving and Kernel's default stealth proxy together; use --captcha-solver and an explicit pool proxy instead") + browserPoolsCreateCmd.Flags().Bool("captcha-solver", false, "Enable automatic CAPTCHA solving for browsers warmed into the pool; does not change proxy egress") browserPoolsCreateCmd.Flags().Bool("headless", false, "Enable headless mode") browserPoolsCreateCmd.Flags().Bool("kiosk", false, "Enable kiosk mode") browserPoolsCreateCmd.Flags().String("memory", "", "Memory for browsers in the pool. Headless: '1GiB' (default), '2GiB' or '4GiB'. Headful: '8GiB' (default) or '16GiB'") @@ -940,7 +960,8 @@ func init() { browserPoolsUpdateCmd.Flags().Int64("size", 0, "Number of browsers in the pool") browserPoolsUpdateCmd.Flags().Int64("fill-rate", 0, "Fill rate per minute") browserPoolsUpdateCmd.Flags().Int64("timeout", 0, "Idle timeout in seconds") - browserPoolsUpdateCmd.Flags().Bool("stealth", false, "Enable stealth mode") + browserPoolsUpdateCmd.Flags().Bool("stealth", false, "Deprecated compatibility mode: enable CAPTCHA solving and Kernel's default stealth proxy together; use --captcha-solver and an explicit pool proxy instead") + browserPoolsUpdateCmd.Flags().Bool("captcha-solver", false, "Set automatic CAPTCHA solving for newly-warmed browsers; does not change proxy egress; use --captcha-solver=false to disable") browserPoolsUpdateCmd.Flags().Bool("headless", false, "Enable headless mode") browserPoolsUpdateCmd.Flags().Bool("kiosk", false, "Enable kiosk mode") browserPoolsUpdateCmd.Flags().String("memory", "", "Memory for newly-warmed browsers in the pool. Headless: '1GiB', '2GiB' or '4GiB'. Headful: '8GiB' or '16GiB'. Existing browsers keep their allocation; use --discard-all-idle to replace idle browsers") @@ -1032,6 +1053,7 @@ func runBrowserPoolsCreate(cmd *cobra.Command, args []string) error { fillRate, _ := cmd.Flags().GetInt64("fill-rate") timeout, _ := cmd.Flags().GetInt64("timeout") stealth, _ := cmd.Flags().GetBool("stealth") + captchaSolver, _ := cmd.Flags().GetBool("captcha-solver") headless, _ := cmd.Flags().GetBool("headless") kiosk, _ := cmd.Flags().GetBool("kiosk") memory, _ := cmd.Flags().GetString("memory") @@ -1059,6 +1081,7 @@ func runBrowserPoolsCreate(cmd *cobra.Command, args []string) error { FillRate: fillRate, TimeoutSeconds: timeout, Stealth: BoolFlag{Set: cmd.Flags().Changed("stealth"), Value: stealth}, + CaptchaSolver: BoolFlag{Set: cmd.Flags().Changed("captcha-solver"), Value: captchaSolver}, Headless: BoolFlag{Set: cmd.Flags().Changed("headless"), Value: headless}, Kiosk: BoolFlag{Set: cmd.Flags().Changed("kiosk"), Value: kiosk}, Memory: memory, @@ -1101,6 +1124,7 @@ func runBrowserPoolsUpdate(cmd *cobra.Command, args []string) error { fillRate, _ := cmd.Flags().GetInt64("fill-rate") timeout, _ := cmd.Flags().GetInt64("timeout") stealth, _ := cmd.Flags().GetBool("stealth") + captchaSolver, _ := cmd.Flags().GetBool("captcha-solver") headless, _ := cmd.Flags().GetBool("headless") kiosk, _ := cmd.Flags().GetBool("kiosk") memory, _ := cmd.Flags().GetString("memory") @@ -1138,6 +1162,7 @@ func runBrowserPoolsUpdate(cmd *cobra.Command, args []string) error { FillRate: Int64Flag{Set: cmd.Flags().Changed("fill-rate"), Value: fillRate}, TimeoutSeconds: timeout, Stealth: BoolFlag{Set: cmd.Flags().Changed("stealth"), Value: stealth}, + CaptchaSolver: BoolFlag{Set: cmd.Flags().Changed("captcha-solver"), Value: captchaSolver}, Headless: BoolFlag{Set: cmd.Flags().Changed("headless"), Value: headless}, Kiosk: BoolFlag{Set: cmd.Flags().Changed("kiosk"), Value: kiosk}, Memory: memory, diff --git a/cmd/browser_pools_test.go b/cmd/browser_pools_test.go index 724b7454..3b1edd42 100644 --- a/cmd/browser_pools_test.go +++ b/cmd/browser_pools_test.go @@ -194,6 +194,47 @@ func TestBrowserPoolsCreate_WithRegion(t *testing.T) { assert.Error(t, c.Create(context.Background(), BrowserPoolsCreateInput{Size: 1, Region: "emea"})) } +func TestBrowserPoolsCreateAndUpdate_CaptchaSolver(t *testing.T) { + setupStdoutCapture(t) + + var created kernel.BrowserPoolNewParams + var updated kernel.BrowserPoolUpdateParams + fake := &FakeBrowserPoolsService{ + NewFunc: func(ctx context.Context, body kernel.BrowserPoolNewParams, opts ...option.RequestOption) (*kernel.BrowserPool, error) { + created = body + return &kernel.BrowserPool{ID: "pool-1"}, nil + }, + UpdateFunc: func(ctx context.Context, id string, body kernel.BrowserPoolUpdateParams, opts ...option.RequestOption) (*kernel.BrowserPool, error) { + updated = body + return &kernel.BrowserPool{ID: id}, nil + }, + } + c := BrowserPoolsCmd{client: fake} + + require.NoError(t, c.Create(context.Background(), BrowserPoolsCreateInput{ + Size: 1, + CaptchaSolver: BoolFlag{Set: true, Value: true}, + })) + createdJSON, err := json.Marshal(created) + require.NoError(t, err) + assert.Contains(t, string(createdJSON), `"captcha_solver":{"enabled":true}`) + + require.NoError(t, c.Update(context.Background(), BrowserPoolsUpdateInput{ + IDOrName: "pool-1", + CaptchaSolver: BoolFlag{Set: true, Value: false}, + })) + updatedJSON, err := json.Marshal(updated) + require.NoError(t, err) + assert.Contains(t, string(updatedJSON), `"captcha_solver":{"enabled":false}`) + + err = c.Create(context.Background(), BrowserPoolsCreateInput{ + Size: 1, + Stealth: BoolFlag{Set: true, Value: true}, + CaptchaSolver: BoolFlag{Set: true, Value: false}, + }) + require.ErrorContains(t, err, "--stealth=true") +} + func TestBrowserPoolsGet_ShowsRegion(t *testing.T) { setupStdoutCapture(t) diff --git a/cmd/browser_proxy.go b/cmd/browser_proxy.go index 627646f8..6cc187d0 100644 --- a/cmd/browser_proxy.go +++ b/cmd/browser_proxy.go @@ -1,16 +1,17 @@ package cmd import ( + "encoding/json" "fmt" "strings" kernel "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/packages/param" ) // proxyModes are the values accepted by --proxy-mode. direct forces egress -// without a proxy regardless of stealth; default restores the browser's -// stealth-derived default (Kernel's stealth proxy when stealth is on, direct -// egress otherwise). +// without a proxy. default uses Kernel's default stealth proxy when CAPTCHA +// solving is enabled and direct egress otherwise. var proxyModes = []string{ string(kernel.BrowserProxyModeDirect), string(kernel.BrowserProxyModeDefault), @@ -25,6 +26,21 @@ type proxySelection struct { Mode string } +func validateStealthCaptchaFlags(stealth, captchaSolver BoolFlag) error { + if stealth.Set && stealth.Value && captchaSolver.Set && !captchaSolver.Value { + return fmt.Errorf("--stealth=true cannot be combined with --captcha-solver=false; use explicit --captcha-solver and --proxy-mode settings instead") + } + return nil +} + +// browserCaptchaSolverParam uses an explicit JSON override because the SDK's +// optional object would otherwise treat {enabled:false} as its zero value and +// omit it, making --captcha-solver=false unable to disable an existing setting. +func browserCaptchaSolverParam(enabled bool) kernel.BrowserCaptchaSolverParam { + raw := json.RawMessage(fmt.Sprintf(`{"enabled":%t}`, enabled)) + return param.Override[kernel.BrowserCaptchaSolverParam](raw) +} + // set reports whether any proxy flag was provided. func (p proxySelection) set() bool { return p.ID != "" || p.Name != "" || p.Mode != "" diff --git a/cmd/browsers.go b/cmd/browsers.go index c465dfdc..079f94e0 100644 --- a/cmd/browsers.go +++ b/cmd/browsers.go @@ -239,10 +239,12 @@ func parseFingerprintOS(os string) (kernel.BrowserFingerprintOs, error) { if os == "" { return "", nil } - if os == string(kernel.BrowserFingerprintOsMacos) { - return kernel.BrowserFingerprintOsMacos, nil + switch kernel.BrowserFingerprintOs(os) { + case kernel.BrowserFingerprintOsLinux, kernel.BrowserFingerprintOsMacos: + return kernel.BrowserFingerprintOs(os), nil + default: + return "", fmt.Errorf("invalid --fingerprint-os value: %s (must be linux or macos)", os) } - return "", fmt.Errorf("invalid --fingerprint-os value: %s (must be macos)", os) } // maxPrivateHosts mirrors the API's cap on network.private_hosts entries. @@ -536,6 +538,7 @@ func formatTags(tags kernel.Tags) string { type BrowsersCreateInput struct { TimeoutSeconds int Stealth BoolFlag + CaptchaSolver BoolFlag Headless BoolFlag GPU BoolFlag Memory string @@ -813,6 +816,9 @@ func (b BrowsersCmd) Create(ctx context.Context, in BrowsersCreateInput) error { if err := validateStartURLFlag(in.StartURL); err != nil { return err } + if err := validateStealthCaptchaFlags(in.Stealth, in.CaptchaSolver); err != nil { + return err + } vaults, err := buildBrowserVaults(in.Vaults) if err != nil { return err @@ -824,6 +830,9 @@ func (b BrowsersCmd) Create(ctx context.Context, in BrowsersCreateInput) error { if in.Stealth.Set { params.Stealth = kernel.Opt(in.Stealth.Value) } + if in.CaptchaSolver.Set { + params.CaptchaSolver = browserCaptchaSolverParam(in.CaptchaSolver.Value) + } if in.Headless.Set { params.Headless = kernel.Opt(in.Headless.Value) } @@ -874,7 +883,8 @@ func (b BrowsersCmd) Create(ctx context.Context, in BrowsersCreateInput) error { } // Add proxy if specified. Omitting it lets the browser default apply: - // Kernel's default stealth proxy for stealth sessions, direct egress otherwise. + // Kernel's default stealth proxy when CAPTCHA solving is enabled and direct + // egress otherwise. sel := proxySelection{ID: in.ProxyID, Name: in.ProxyName, Mode: in.ProxyMode} if sel.set() { proxy, err := buildProxyConfigParam(sel) @@ -1003,6 +1013,13 @@ func (b BrowsersCmd) Create(ctx context.Context, in BrowsersCreateInput) error { tableData := buildBrowserTableData(browser.SessionID, browser.CdpWsURL, browser.BrowserLiveViewURL, browser.Profile, browser.ProfileSaveChanges, browser.StartURL, browser.Name, browser.Tags) tableData = appendBrowserLeasedAtRow(tableData, browser.LeasedAt) tableData = appendReplayRows(tableData, browser.Replay.ReplayID, browser.Replay.ReplayViewURL, browser.Replay.StartedAt, browser.Replay.FinishedAt) + tableData = append(tableData, []string{"CAPTCHA Solver", fmt.Sprintf("%t", browser.CaptchaSolver.Enabled)}) + if browser.Fingerprint.Os != "" { + tableData = append(tableData, []string{"Fingerprint OS", string(browser.Fingerprint.Os)}) + } + if proxy := formatBrowserProxy(browser.Proxy); proxy != "" { + tableData = append(tableData, []string{"Proxy", proxy}) + } tableData = append(tableData, []string{"Private Hosts", formatPrivateHosts(browser.Network)}, []string{"Allowed Hosts", formatAllowedHosts(browser.Network)}, []string{"Proxy Routes", formatProxyRoutes(browser.Network)}) tableData = append(tableData, browserLocationRows(browser.Location)...) PrintTableNoPad(tableData, true) @@ -1023,6 +1040,10 @@ func printBrowserPoolAcquireResult(resp *kernel.BrowserPoolAcquireResponse) { tableData := buildBrowserTableData(resp.SessionID, resp.CdpWsURL, resp.BrowserLiveViewURL, resp.Profile, resp.ProfileSaveChanges, resp.StartURL, resp.Name, resp.Tags) tableData = appendBrowserLeasedAtRow(tableData, resp.LeasedAt) tableData = appendReplayRows(tableData, resp.Replay.ReplayID, resp.Replay.ReplayViewURL, resp.Replay.StartedAt, resp.Replay.FinishedAt) + tableData = append(tableData, []string{"CAPTCHA Solver", fmt.Sprintf("%t", resp.CaptchaSolver.Enabled)}) + if resp.Fingerprint.Os != "" { + tableData = append(tableData, []string{"Fingerprint OS", string(resp.Fingerprint.Os)}) + } PrintTableNoPad(tableData, true) } @@ -1208,7 +1229,11 @@ func (b BrowsersCmd) Get(ctx context.Context, in BrowsersGetInput) error { tableData = append(tableData, browserLocationRows(browser.Location)...) tableData = append(tableData, []string{"Timeout (seconds)", fmt.Sprintf("%d", browser.TimeoutSeconds)}) tableData = append(tableData, []string{"Headless", fmt.Sprintf("%t", browser.Headless)}) - tableData = append(tableData, []string{"Stealth", fmt.Sprintf("%t", browser.Stealth)}) + tableData = append(tableData, []string{"Stealth (deprecated)", fmt.Sprintf("%t", browser.Stealth)}) + tableData = append(tableData, []string{"CAPTCHA Solver", fmt.Sprintf("%t", browser.CaptchaSolver.Enabled)}) + if browser.Fingerprint.Os != "" { + tableData = append(tableData, []string{"Fingerprint OS", string(browser.Fingerprint.Os)}) + } tableData = append(tableData, []string{"GPU", fmt.Sprintf("%t", browser.GPU)}) tableData = append(tableData, []string{"Memory", util.OrDash(string(browser.Memory))}) if browser.VideoMemory != "" { @@ -3386,9 +3411,9 @@ func init() { addJSONOutputFlag(browsersUpdateCmd) browsersUpdateCmd.Flags().String("proxy-id", "", "ID of the proxy to use for the browser session (mutually exclusive with --proxy-name and --proxy-mode)") browsersUpdateCmd.Flags().String("proxy-name", "", "Name of the proxy to use for the browser session; must match exactly one active proxy in the project (mutually exclusive with --proxy-id and --proxy-mode)") - browsersUpdateCmd.Flags().String("proxy-mode", "", "Proxy egress mode instead of a selected proxy: 'direct' for no proxy regardless of stealth, or 'default' to restore the browser default (Kernel's stealth proxy when stealth is on, direct egress otherwise)") - browsersUpdateCmd.Flags().Bool("clear-proxy", false, "Drop the selected proxy and restore the browser default (same as --proxy-mode=default)") - browsersUpdateCmd.Flags().Bool("disable-default-proxy", false, "Connect directly instead of through the default stealth proxy (same as --proxy-mode=direct); use --disable-default-proxy=false to restore the default") + browsersUpdateCmd.Flags().String("proxy-mode", "", "Proxy egress mode instead of a selected proxy: 'direct' for no proxy, or 'default' for Kernel's default stealth proxy when CAPTCHA solving is enabled and direct egress otherwise") + browsersUpdateCmd.Flags().Bool("clear-proxy", false, "Drop the selected proxy and restore default egress (same as --proxy-mode=default): Kernel's default stealth proxy with CAPTCHA solving, direct otherwise") + browsersUpdateCmd.Flags().Bool("disable-default-proxy", false, "Connect directly instead of through the default stealth proxy (same as --proxy-mode=direct); CAPTCHA solving remains enabled; use --disable-default-proxy=false to restore default egress") browsersUpdateCmd.Flags().String("profile-id", "", "Profile ID to load into the browser session (mutually exclusive with --profile-name)") browsersUpdateCmd.Flags().String("profile-name", "", "Profile name to load into the browser session (mutually exclusive with --profile-id)") browsersUpdateCmd.Flags().Bool("save-changes", false, "If set, save changes back to the profile when the session ends") @@ -3687,12 +3712,13 @@ unrestricted code execution inside the browser VM and is not sandboxed.`, // Add flags for create command addJSONOutputFlag(browsersCreateCmd) - browsersCreateCmd.Flags().BoolP("stealth", "s", false, "Launch browser in stealth mode to avoid detection") + browsersCreateCmd.Flags().BoolP("stealth", "s", false, "Deprecated compatibility mode: enable CAPTCHA solving and Kernel's default stealth proxy together; use --captcha-solver and --proxy-mode instead") + browsersCreateCmd.Flags().Bool("captcha-solver", false, "Enable automatic CAPTCHA solving; does not change proxy egress, so select --proxy-mode=default for Kernel's default stealth proxy") browsersCreateCmd.Flags().BoolP("headless", "H", false, "Launch browser without GUI access") browsersCreateCmd.Flags().Bool("gpu", false, "Launch browser with hardware-accelerated GPU rendering") browsersCreateCmd.Flags().String("memory", "", "Memory for a non-GPU browser session. Headless: '1GiB' (default), '2GiB' or '4GiB'. Headful: '8GiB' (default) or '16GiB'") browsersCreateCmd.Flags().String("video-memory", "", "Video memory (VRAM) for a GPU browser session (requires --gpu): '3GiB' (default, 4 vCPU/6GiB memory) or '6GiB' (8 vCPU/12GiB memory)") - browsersCreateCmd.Flags().String("fingerprint-os", "", "Closed beta browser fingerprint OS override: macos. Contact Kernel to enable; requires --stealth=true, --headless=false, --gpu=false, and default memory") + browsersCreateCmd.Flags().String("fingerprint-os", "", "Closed beta browser fingerprint OS override: linux or macos. Contact Kernel to enable; requires --captcha-solver=true, --headless=false, --gpu=false, and default memory") browsersCreateCmd.Flags().String("invocation-id", "", "Associate the browser session with an invocation") browsersCreateCmd.Flags().Bool("kiosk", false, "Launch browser in kiosk mode") browsersCreateCmd.Flags().IntP("timeout", "t", 60, "Timeout in seconds for the browser session") @@ -3701,7 +3727,7 @@ unrestricted code execution inside the browser VM and is not sandboxed.`, browsersCreateCmd.Flags().Bool("save-changes", false, "If set, save changes back to the profile when the session ends") browsersCreateCmd.Flags().String("proxy-id", "", "Proxy ID to use for the browser session (mutually exclusive with --proxy-name and --proxy-mode)") browsersCreateCmd.Flags().String("proxy-name", "", "Proxy name to use for the browser session; must match exactly one active proxy in the project (mutually exclusive with --proxy-id and --proxy-mode)") - browsersCreateCmd.Flags().String("proxy-mode", "", "Proxy egress mode instead of a selected proxy: 'direct' for no proxy regardless of stealth, or 'default' for the browser default (Kernel's stealth proxy when --stealth is set, direct egress otherwise)") + browsersCreateCmd.Flags().String("proxy-mode", "", "Proxy egress mode instead of a selected proxy: 'direct' for no proxy, or 'default' for Kernel's default stealth proxy when CAPTCHA solving is enabled and direct egress otherwise") browsersCreateCmd.Flags().String("region", "", "Geographic region for the session: 'us-east', 'us-west', 'eu-west', or 'ap-southeast'. Fixed once the session is created; requires a Start-Up or Enterprise plan and defaults to us-east") browsersCreateCmd.Flags().StringSlice("private-host", nil, "Destinations the browser reaches directly through its own network instead of Kernel-managed egress, for private hosts on a VPN or tunnel the session joins (repeat or comma-separated, max 32). Accepts hostname patterns ('*.example.ts.net'), IPs ('10.1.30.63', '[fd00::1]'), and private CIDRs ('100.64.0.0/10'). Replaces the default private ranges (RFC1918, 100.64.0.0/10, fc00::/7); omit to keep them. Fixed once the session is created") browsersCreateCmd.Flags().StringSlice("allowed-host", nil, "Set an egress allowlist at creation: the only destinations the browser may reach through Kernel-managed egress (repeat or comma-separated, max 100); anything else is refused with a 403 (network_policy_denied). Filters Kernel-managed egress only, not all browser VM traffic. Accepts exact hostnames ('example.com'), a leading wildcard matching subdomains only ('*.example.com'), public IPs ('8.8.8.8', '[2001:4860:4860::8888]'), and public CIDRs ('8.8.4.0/24'). No ports, paths, or schemes. --start-url must be allowed. Omit for unfiltered egress; an empty list is invalid. Requires proxy v3; cannot be combined with --pool-id or --pool-name, even with --yes. An existing list can be replaced or removed with 'browsers update'; it cannot be added later if omitted at creation or removed") @@ -3834,6 +3860,7 @@ func runBrowsersCreate(cmd *cobra.Command, args []string) error { // Get flag values stealthVal, _ := cmd.Flags().GetBool("stealth") + captchaSolverVal, _ := cmd.Flags().GetBool("captcha-solver") headlessVal, _ := cmd.Flags().GetBool("headless") gpuVal, _ := cmd.Flags().GetBool("gpu") memory, _ := cmd.Flags().GetString("memory") @@ -3996,6 +4023,7 @@ func runBrowsersCreate(cmd *cobra.Command, args []string) error { in := BrowsersCreateInput{ TimeoutSeconds: timeout, Stealth: BoolFlag{Set: cmd.Flags().Changed("stealth"), Value: stealthVal}, + CaptchaSolver: BoolFlag{Set: cmd.Flags().Changed("captcha-solver"), Value: captchaSolverVal}, Headless: BoolFlag{Set: cmd.Flags().Changed("headless"), Value: headlessVal}, GPU: BoolFlag{Set: cmd.Flags().Changed("gpu"), Value: gpuVal}, Memory: memory, diff --git a/cmd/browsers_test.go b/cmd/browsers_test.go index 03188dc5..15f625e2 100644 --- a/cmd/browsers_test.go +++ b/cmd/browsers_test.go @@ -1206,9 +1206,38 @@ func TestBrowsersCreate_WithFingerprintOS(t *testing.T) { require.NoError(t, err) assert.Contains(t, string(raw), `"fingerprint":{"os":"macos"}`) + err = b.Create(context.Background(), BrowsersCreateInput{FingerprintOS: "linux"}) + require.NoError(t, err) + assert.Equal(t, kernel.BrowserFingerprintOsLinux, captured.Fingerprint.Os) + err = b.Create(context.Background(), BrowsersCreateInput{FingerprintOS: "windows"}) require.ErrorContains(t, err, "--fingerprint-os") - assert.Equal(t, 1, calls) + assert.Equal(t, 2, calls) +} + +func TestBrowsersCreate_WithCaptchaSolver(t *testing.T) { + setupStdoutCapture(t) + + var captured kernel.BrowserNewParams + fake := &FakeBrowsersService{ + NewFunc: func(ctx context.Context, body kernel.BrowserNewParams, opts ...option.RequestOption) (*kernel.BrowserNewResponse, error) { + captured = body + return &kernel.BrowserNewResponse{SessionID: "sess-captcha"}, nil + }, + } + b := BrowsersCmd{browsers: fake} + + err := b.Create(context.Background(), BrowsersCreateInput{CaptchaSolver: BoolFlag{Set: true, Value: true}}) + require.NoError(t, err) + raw, err := captured.MarshalJSON() + require.NoError(t, err) + assert.Contains(t, string(raw), `"captcha_solver":{"enabled":true}`) + + err = b.Create(context.Background(), BrowsersCreateInput{ + Stealth: BoolFlag{Set: true, Value: true}, + CaptchaSolver: BoolFlag{Set: true, Value: false}, + }) + require.ErrorContains(t, err, "--stealth=true") } func TestBrowsersCreate_WithChromePolicy(t *testing.T) { diff --git a/cmd/report_types.go b/cmd/report_types.go new file mode 100644 index 00000000..409e8756 --- /dev/null +++ b/cmd/report_types.go @@ -0,0 +1,237 @@ +package cmd + +import ( + "context" + "encoding/json" + "fmt" + "strconv" + "strings" + + "github.com/kernel/cli/pkg/util" + kernel "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + "github.com/kernel/kernel-go-sdk/packages/pagination" + "github.com/pterm/pterm" + "github.com/spf13/cobra" +) + +// ReportTypesService defines the report type SDK methods exposed by the CLI. +type ReportTypesService interface { + Get(ctx context.Context, typeName string, opts ...option.RequestOption) (*kernel.ReportType, error) + List(ctx context.Context, query kernel.ReportTypeListParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.ReportTypeSummary], error) +} + +type ReportTypeVersionsService interface { + Get(ctx context.Context, version int64, query kernel.ReportTypeVersionGetParams, opts ...option.RequestOption) (*kernel.ReportTypeVersion, error) +} + +type ReportTypesCmd struct { + reportTypes ReportTypesService + versions ReportTypeVersionsService +} + +type ReportTypesListInput struct { + TaskID string + Page int + PerPage int + Output string +} + +type ReportTypesGetInput struct { + Type string + Output string +} + +type ReportTypeVersionsGetInput struct { + Type string + Version int64 + Output string +} + +func (c ReportTypesCmd) List(ctx context.Context, in ReportTypesListInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + if strings.TrimSpace(in.TaskID) == "" { + return fmt.Errorf("--task-id is required") + } + page, perPage, err := normalizePageInput(in.Page, in.PerPage) + if err != nil { + return err + } + result, err := c.reportTypes.List(ctx, kernel.ReportTypeListParams{ + TaskID: in.TaskID, + Limit: kernel.Opt(int64(perPage + 1)), + Offset: kernel.Opt(int64((page - 1) * perPage)), + }) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + var items []kernel.ReportTypeSummary + if result != nil { + items = result.Items + } + hasMore := len(items) > perPage + if hasMore { + items = items[:perPage] + } + if in.Output == "json" { + return util.PrintPageJSON(items, page, perPage, hasMore) + } + + if len(items) == 0 { + pterm.Info.Println("No report types found") + } else { + rows := pterm.TableData{{"Type", "Latest Version", "Description"}} + for _, reportType := range items { + rows = append(rows, []string{reportType.Type, fmt.Sprint(reportType.LatestVersion), reportType.Description}) + } + PrintTableNoPad(rows, true) + } + + next := fmt.Sprintf("kernel report-types list --page %d --per-page %d --task-id %q", page+1, perPage, in.TaskID) + printListPaginationFooter(page, perPage, len(items), hasMore, next) + return nil +} + +func (c ReportTypesCmd) Get(ctx context.Context, in ReportTypesGetInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + reportType, err := c.reportTypes.Get(ctx, in.Type) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(reportType) + } + return printReportTypeDetail(reportType) +} + +func (c ReportTypesCmd) GetVersion(ctx context.Context, in ReportTypeVersionsGetInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + if in.Version < 1 { + return fmt.Errorf("version must be at least 1") + } + version, err := c.versions.Get(ctx, in.Version, kernel.ReportTypeVersionGetParams{Type: in.Type}) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(version) + } + rows := pterm.TableData{ + {"Property", "Value"}, + {"Type", version.Type}, + {"Version", fmt.Sprint(version.Version)}, + {"Retired", strconv.FormatBool(version.Retired)}, + } + PrintTableNoPad(rows, true) + return printReportSchema(version.Schema) +} + +func printReportTypeDetail(reportType *kernel.ReportType) error { + versions := make([]string, 0, len(reportType.Versions)) + for _, version := range reportType.Versions { + label := fmt.Sprint(version.Version) + if version.Retired { + label += " (retired)" + } + versions = append(versions, label) + } + rows := pterm.TableData{ + {"Property", "Value"}, + {"Type", reportType.Type}, + {"Description", reportType.Description}, + {"Latest Version", fmt.Sprint(reportType.LatestVersion)}, + {"Versions", util.OrDash(strings.Join(versions, ", "))}, + } + PrintTableNoPad(rows, true) + return printReportSchema(reportType.Schema) +} + +func printReportSchema(schema map[string]any) error { + data, err := json.MarshalIndent(schema, "", " ") + if err != nil { + return err + } + pterm.Info.Println("Schema:") + fmt.Println(string(data)) + return nil +} + +var reportTypesCmd = &cobra.Command{ + Use: "report-types", + Aliases: []string{"report-type"}, + Short: "Discover report types and their schemas", + Long: "Discover the report types available for a task and inspect each immutable JSON Schema version before submitting reports.", +} + +var reportTypesListCmd = &cobra.Command{ + Use: "list", + Short: "List report types available for a task", + Long: "List the report types an agent can submit for a task. Use kernel report-types get to inspect the latest JSON Schema for a type.", + Args: cobra.NoArgs, + RunE: runReportTypesList, +} + +var reportTypesGetCmd = &cobra.Command{ + Use: "get ", + Short: "Get a report type and its latest schema", + Long: "Get a report type, all of its versions, and the JSON Schema for its latest non-retired version.", + Args: cobra.ExactArgs(1), + RunE: runReportTypesGet, +} + +var reportTypeVersionsCmd = &cobra.Command{ + Use: "versions", + Short: "Inspect immutable report type schema versions", +} + +var reportTypeVersionsGetCmd = &cobra.Command{ + Use: "get ", + Short: "Get one report type schema version", + Long: "Get one immutable JSON Schema version of a report type, including a retired version.", + Args: cobra.ExactArgs(2), + RunE: runReportTypeVersionsGet, +} + +func init() { + reportTypesCmd.AddCommand(reportTypesListCmd, reportTypesGetCmd, reportTypeVersionsCmd) + reportTypeVersionsCmd.AddCommand(reportTypeVersionsGetCmd) + + reportTypesListCmd.Flags().String("task-id", "", "Task the agent is finding a report type for (required)") + reportTypesListCmd.Flags().Int("page", 1, "Page number (1-based)") + reportTypesListCmd.Flags().Int("per-page", 20, "Items per page (1-99, default 20)") + _ = reportTypesListCmd.MarkFlagRequired("task-id") + addJSONOutputFlag(reportTypesListCmd) + addJSONOutputFlag(reportTypesGetCmd) + addJSONOutputFlag(reportTypeVersionsGetCmd) +} + +func runReportTypesList(cmd *cobra.Command, args []string) error { + taskID, _ := cmd.Flags().GetString("task-id") + page, _ := cmd.Flags().GetInt("page") + perPage, _ := cmd.Flags().GetInt("per-page") + output, _ := cmd.Flags().GetString("output") + client := getKernelClient(cmd) + return (ReportTypesCmd{reportTypes: &client.ReportTypes}).List(cmd.Context(), ReportTypesListInput{TaskID: taskID, Page: page, PerPage: perPage, Output: output}) +} + +func runReportTypesGet(cmd *cobra.Command, args []string) error { + output, _ := cmd.Flags().GetString("output") + client := getKernelClient(cmd) + return (ReportTypesCmd{reportTypes: &client.ReportTypes}).Get(cmd.Context(), ReportTypesGetInput{Type: args[0], Output: output}) +} + +func runReportTypeVersionsGet(cmd *cobra.Command, args []string) error { + version, err := strconv.ParseInt(args[1], 10, 64) + if err != nil { + return fmt.Errorf("version must be an integer of at least 1") + } + output, _ := cmd.Flags().GetString("output") + client := getKernelClient(cmd) + return (ReportTypesCmd{versions: &client.ReportTypes.Versions}).GetVersion(cmd.Context(), ReportTypeVersionsGetInput{Type: args[0], Version: version, Output: output}) +} diff --git a/cmd/reports.go b/cmd/reports.go new file mode 100644 index 00000000..53299590 --- /dev/null +++ b/cmd/reports.go @@ -0,0 +1,309 @@ +package cmd + +import ( + "context" + "encoding/json" + "fmt" + "io" + "os" + "strings" + + "github.com/kernel/cli/pkg/util" + kernel "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + "github.com/kernel/kernel-go-sdk/packages/pagination" + "github.com/pterm/pterm" + "github.com/spf13/cobra" +) + +// ReportsService defines the report SDK methods exposed by the CLI. +type ReportsService interface { + New(ctx context.Context, body kernel.ReportNewParams, opts ...option.RequestOption) (*kernel.Report, error) + Get(ctx context.Context, id string, opts ...option.RequestOption) (*kernel.Report, error) + List(ctx context.Context, query kernel.ReportListParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.Report], error) +} + +type ReportsCmd struct { + reports ReportsService +} + +type ReportsCreateInput struct { + TaskID string + Type string + Data string + OccurredAt string + SchemaVersion int64 + SessionID string + Output string +} + +type ReportsGetInput struct { + ID string + Output string +} + +type ReportsListInput struct { + TaskID string + Type string + Page int + PerPage int + Output string +} + +func parseReportData(raw string) (map[string]any, error) { + decoder := json.NewDecoder(strings.NewReader(raw)) + decoder.UseNumber() + var data map[string]any + if err := decoder.Decode(&data); err != nil || data == nil { + return nil, fmt.Errorf("--data must be a JSON object") + } + if err := decoder.Decode(&struct{}{}); err != io.EOF { + return nil, fmt.Errorf("--data must contain exactly one JSON object") + } + encoded, err := json.Marshal(data) + if err != nil { + return nil, fmt.Errorf("--data must be a JSON object") + } + if len(encoded) > 16*1024 { + return nil, fmt.Errorf("--data must encode to at most 16 KB of JSON") + } + return data, nil +} + +func (c ReportsCmd) Create(ctx context.Context, in ReportsCreateInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + if strings.TrimSpace(in.TaskID) == "" { + return fmt.Errorf("--task-id is required") + } + if strings.TrimSpace(in.Type) == "" { + return fmt.Errorf("--type is required") + } + data, err := parseReportData(in.Data) + if err != nil { + return err + } + params := kernel.ReportNewParams{TaskID: in.TaskID, Type: in.Type, Data: data} + if in.OccurredAt != "" { + occurredAt, err := parseRFC3339Flag("--occurred-at", in.OccurredAt) + if err != nil { + return err + } + params.OccurredAt = kernel.Opt(occurredAt) + } + if in.SchemaVersion != 0 { + if in.SchemaVersion < 1 { + return fmt.Errorf("--schema-version must be at least 1") + } + params.SchemaVersion = kernel.Opt(in.SchemaVersion) + } + if in.SessionID != "" { + params.SessionID = kernel.Opt(in.SessionID) + } + + report, err := c.reports.New(ctx, params) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(report) + } + pterm.Success.Printf("Submitted report: %s\n", report.ID) + return printReportDetail(report) +} + +func (c ReportsCmd) Get(ctx context.Context, in ReportsGetInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + report, err := c.reports.Get(ctx, in.ID) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(report) + } + return printReportDetail(report) +} + +func (c ReportsCmd) List(ctx context.Context, in ReportsListInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + if strings.TrimSpace(in.TaskID) == "" { + return fmt.Errorf("--task-id is required") + } + page, perPage, err := normalizePageInput(in.Page, in.PerPage) + if err != nil { + return err + } + params := kernel.ReportListParams{ + TaskID: in.TaskID, + Limit: kernel.Opt(int64(perPage + 1)), + Offset: kernel.Opt(int64((page - 1) * perPage)), + } + if in.Type != "" { + params.Type = kernel.Opt(in.Type) + } + result, err := c.reports.List(ctx, params) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + var items []kernel.Report + if result != nil { + items = result.Items + } + hasMore := len(items) > perPage + if hasMore { + items = items[:perPage] + } + if in.Output == "json" { + return util.PrintPageJSON(items, page, perPage, hasMore) + } + + if len(items) == 0 { + pterm.Info.Println("No reports found") + } else { + rows := pterm.TableData{{"Report ID", "Type", "Schema Version", "Browser ID", "Occurred At", "Submitted At"}} + for _, report := range items { + rows = append(rows, []string{ + report.ID, + report.Type, + fmt.Sprint(report.SchemaVersion), + util.OrDash(report.SessionID), + util.FormatLocal(report.OccurredAt), + util.FormatLocal(report.CreatedAt), + }) + } + PrintTableNoPad(rows, true) + } + + next := fmt.Sprintf("kernel reports list --page %d --per-page %d --task-id %q", page+1, perPage, in.TaskID) + if in.Type != "" { + next += fmt.Sprintf(" --type %q", in.Type) + } + printListPaginationFooter(page, perPage, len(items), hasMore, next) + return nil +} + +func printReportDetail(report *kernel.Report) error { + rows := pterm.TableData{ + {"Property", "Value"}, + {"ID", report.ID}, + {"Task ID", report.TaskID}, + {"Browser ID", util.OrDash(report.SessionID)}, + {"Type", report.Type}, + {"Schema Version", fmt.Sprint(report.SchemaVersion)}, + {"Occurred At", util.FormatLocal(report.OccurredAt)}, + {"Submitted At", util.FormatLocal(report.CreatedAt)}, + } + PrintTableNoPad(rows, true) + data, err := json.MarshalIndent(report.Data, "", " ") + if err != nil { + return err + } + pterm.Info.Println("Data:") + fmt.Println(string(data)) + return nil +} + +var reportsCmd = &cobra.Command{ + Use: "reports", + Aliases: []string{"report"}, + Short: "Submit and inspect typed task reports", + Long: "Submit immutable, schema-validated reports against tasks and list the reports already submitted.", +} + +var reportsCreateCmd = &cobra.Command{ + Use: "create", + Short: "Submit a typed report against a task", + Long: "Submit a report whose --data matches the selected report type schema. A validation error identifies each invalid field, and a task can have at most 500 reports.", + Args: cobra.NoArgs, + RunE: runReportsCreate, +} + +var reportsGetCmd = &cobra.Command{ + Use: "get ", + Short: "Get a report", + Args: cobra.ExactArgs(1), + RunE: runReportsGet, +} + +var reportsListCmd = &cobra.Command{ + Use: "list", + Short: "List a task's reports, oldest first", + Args: cobra.NoArgs, + RunE: runReportsList, +} + +func init() { + reportsCmd.AddCommand(reportsCreateCmd, reportsGetCmd, reportsListCmd) + + reportsCreateCmd.Flags().String("task-id", "", "ID of the task to report against (required)") + reportsCreateCmd.Flags().String("type", "", "Report type name from kernel report-types list (required; maximum 128 characters)") + reportsCreateCmd.Flags().String("data", "", "Report data as a JSON object matching the report type schema (maximum 16 KB encoded; required unless --data-file is used)") + reportsCreateCmd.Flags().String("data-file", "", "Read report data as a JSON object from a file, or '-' for stdin (maximum 16 KB encoded)") + reportsCreateCmd.Flags().String("occurred-at", "", "When the reported event happened as RFC3339; defaults to submission time and must be within 30 days past to 5 minutes future") + reportsCreateCmd.Flags().Int64("schema-version", 0, "Report type schema version; defaults to the latest non-retired version") + reportsCreateCmd.Flags().String("session-id", "", "Browser ID where the event was observed; deleted browsers are accepted and are linked to the task if needed") + reportsCreateCmd.MarkFlagsOneRequired("data", "data-file") + reportsCreateCmd.MarkFlagsMutuallyExclusive("data", "data-file") + _ = reportsCreateCmd.MarkFlagRequired("task-id") + _ = reportsCreateCmd.MarkFlagRequired("type") + addJSONOutputFlag(reportsCreateCmd) + + addJSONOutputFlag(reportsGetCmd) + + reportsListCmd.Flags().String("task-id", "", "Task whose reports to list (required)") + reportsListCmd.Flags().String("type", "", "Only return reports of this type") + reportsListCmd.Flags().Int("page", 1, "Page number (1-based)") + reportsListCmd.Flags().Int("per-page", 20, "Items per page (1-99, default 20)") + _ = reportsListCmd.MarkFlagRequired("task-id") + addJSONOutputFlag(reportsListCmd) +} + +func runReportsCreate(cmd *cobra.Command, args []string) error { + taskID, _ := cmd.Flags().GetString("task-id") + typeName, _ := cmd.Flags().GetString("type") + data, _ := cmd.Flags().GetString("data") + if cmd.Flags().Changed("data-file") { + path, _ := cmd.Flags().GetString("data-file") + var contents []byte + var err error + if path == "-" { + contents, err = io.ReadAll(cmd.InOrStdin()) + } else { + contents, err = os.ReadFile(path) + } + if err != nil { + return fmt.Errorf("failed to read report data file: %w", err) + } + data = string(contents) + } + occurredAt, _ := cmd.Flags().GetString("occurred-at") + schemaVersion, _ := cmd.Flags().GetInt64("schema-version") + sessionID, _ := cmd.Flags().GetString("session-id") + output, _ := cmd.Flags().GetString("output") + client := getKernelClient(cmd) + return (ReportsCmd{reports: &client.Reports}).Create(cmd.Context(), ReportsCreateInput{ + TaskID: taskID, Type: typeName, Data: data, OccurredAt: occurredAt, + SchemaVersion: schemaVersion, SessionID: sessionID, Output: output, + }) +} + +func runReportsGet(cmd *cobra.Command, args []string) error { + output, _ := cmd.Flags().GetString("output") + client := getKernelClient(cmd) + return (ReportsCmd{reports: &client.Reports}).Get(cmd.Context(), ReportsGetInput{ID: args[0], Output: output}) +} + +func runReportsList(cmd *cobra.Command, args []string) error { + taskID, _ := cmd.Flags().GetString("task-id") + typeName, _ := cmd.Flags().GetString("type") + page, _ := cmd.Flags().GetInt("page") + perPage, _ := cmd.Flags().GetInt("per-page") + output, _ := cmd.Flags().GetString("output") + client := getKernelClient(cmd) + return (ReportsCmd{reports: &client.Reports}).List(cmd.Context(), ReportsListInput{TaskID: taskID, Type: typeName, Page: page, PerPage: perPage, Output: output}) +} diff --git a/cmd/root.go b/cmd/root.go index f89b68b8..6af903c4 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -167,6 +167,9 @@ func init() { rootCmd.AddCommand(projectsCmd) rootCmd.AddCommand(orgCmd) rootCmd.AddCommand(profilesCmd) + rootCmd.AddCommand(tasksCmd) + rootCmd.AddCommand(reportsCmd) + rootCmd.AddCommand(reportTypesCmd) rootCmd.AddCommand(proxies.ProxiesCmd) rootCmd.AddCommand(proxies.ProxyIPsCmd) rootCmd.AddCommand(extensionsCmd) diff --git a/cmd/service_accounts.go b/cmd/service_accounts.go new file mode 100644 index 00000000..493fd5a3 --- /dev/null +++ b/cmd/service_accounts.go @@ -0,0 +1,382 @@ +package cmd + +import ( + "context" + "fmt" + + "github.com/kernel/cli/pkg/interactive" + "github.com/kernel/cli/pkg/util" + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + "github.com/kernel/kernel-go-sdk/packages/pagination" + "github.com/pterm/pterm" + "github.com/spf13/cobra" +) + +// ServiceAccountsService is the subset of the SDK service used by the CLI. +type ServiceAccountsService interface { + New(ctx context.Context, body kernel.ServiceAccountNewParams, opts ...option.RequestOption) (*kernel.ServiceAccount, error) + Get(ctx context.Context, id string, opts ...option.RequestOption) (*kernel.ServiceAccount, error) + Update(ctx context.Context, id string, body kernel.ServiceAccountUpdateParams, opts ...option.RequestOption) (*kernel.ServiceAccount, error) + List(ctx context.Context, query kernel.ServiceAccountListParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.ServiceAccount], error) + Delete(ctx context.Context, id string, opts ...option.RequestOption) error +} + +type ServiceAccountsCmd struct { + serviceAccounts ServiceAccountsService + prompter interactive.Prompter +} + +type ServiceAccountsListInput struct { + Page int + PerPage int + Query string + Status string + Output string +} + +type ServiceAccountsGetInput struct { + ID string + Output string +} + +type ServiceAccountsCreateInput struct { + Name string + Description string + Output string +} + +type ServiceAccountsUpdateInput struct { + ID string + ExpectedVersion int64 + Name *string + Description *string + Output string +} + +type ServiceAccountsDeleteInput struct { + ID string + SkipConfirm bool +} + +func (c ServiceAccountsCmd) List(ctx context.Context, in ServiceAccountsListInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + page, perPage, err := normalizePageInput(in.Page, in.PerPage) + if err != nil { + return err + } + status, err := validateWorkloadIdentityListStatus(in.Status) + if err != nil { + return err + } + if len(in.Query) > 256 { + return fmt.Errorf("--query must be at most 256 characters") + } + + params := kernel.ServiceAccountListParams{ + Limit: kernel.Opt(int64(perPage + 1)), + Offset: kernel.Opt(int64((page - 1) * perPage)), + } + if in.Query != "" { + params.Query = kernel.Opt(in.Query) + } + if status != "" { + params.Status = kernel.ServiceAccountListParamsStatus(status) + } + + result, err := c.serviceAccounts.List(ctx, params) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + items := []kernel.ServiceAccount{} + if result != nil { + items = result.Items + } + hasMore := len(items) > perPage + if hasMore { + items = items[:perPage] + } + + if in.Output == "json" { + return util.PrintPageJSON(items, page, perPage, hasMore) + } + if len(items) == 0 { + pterm.Info.Println("No service accounts found") + } else { + rows := pterm.TableData{{"ID", "Name", "Description", "Status", "Security Version", "Last Used At", "Created At"}} + for _, account := range items { + rows = append(rows, []string{ + account.ID, + account.Name, + util.OrDash(account.Description), + workloadIdentityResourceStatus(account.JSON.ArchivedAt.Valid()), + fmt.Sprintf("%d", account.SecurityVersion), + util.FormatLocal(account.LastUsedAt), + util.FormatLocal(account.CreatedAt), + }) + } + PrintTableNoPad(rows, true) + } + + filters := "" + if in.Query != "" { + filters += fmt.Sprintf(" --query %q", in.Query) + } + if status != "" { + filters += fmt.Sprintf(" --status %s", status) + } + nextCommand := fmt.Sprintf("kernel service-accounts list --page %d --per-page %d%s", page+1, perPage, filters) + printListPaginationFooter(page, perPage, len(items), hasMore, nextCommand) + return nil +} + +func (c ServiceAccountsCmd) Get(ctx context.Context, in ServiceAccountsGetInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + account, err := c.serviceAccounts.Get(ctx, in.ID) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(account) + } + printServiceAccountDetail(account) + return nil +} + +func (c ServiceAccountsCmd) Create(ctx context.Context, in ServiceAccountsCreateInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + name, err := validateWorkloadIdentityName(in.Name, "name") + if err != nil { + return err + } + if err := validateWorkloadIdentityDescription(in.Description); err != nil { + return err + } + + params := kernel.ServiceAccountNewParams{ServiceAccountConfig: kernel.ServiceAccountConfigParam{Name: name}} + if in.Description != "" { + params.ServiceAccountConfig.Description = kernel.Opt(in.Description) + } + account, err := c.serviceAccounts.New(ctx, params) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(account) + } + pterm.Success.Printf("Created service account: %s\n", account.ID) + printServiceAccountDetail(account) + return nil +} + +func (c ServiceAccountsCmd) Update(ctx context.Context, in ServiceAccountsUpdateInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + if in.ExpectedVersion < 1 { + return fmt.Errorf("--expected-version must be at least 1") + } + + params := kernel.ServiceAccountUpdateParams{ExpectedVersion: in.ExpectedVersion} + if in.Name != nil { + name, err := validateWorkloadIdentityName(*in.Name, "name") + if err != nil { + return err + } + params.Name = kernel.Opt(name) + } + if in.Description != nil { + if err := validateWorkloadIdentityDescription(*in.Description); err != nil { + return err + } + params.Description = kernel.Opt(*in.Description) + } + if in.Name == nil && in.Description == nil { + return fmt.Errorf("nothing to update: pass --name or --description") + } + + account, err := c.serviceAccounts.Update(ctx, in.ID, params) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(account) + } + pterm.Success.Printf("Updated service account: %s\n", account.ID) + printServiceAccountDetail(account) + return nil +} + +func (c ServiceAccountsCmd) Delete(ctx context.Context, in ServiceAccountsDeleteInput) error { + if !in.SkipConfirm { + ok, err := c.prompter.Confirm( + fmt.Sprintf("archive service account '%s'", in.ID), + fmt.Sprintf("Archive service account '%s'? Existing history is retained, but new tokens will no longer be issued for it.", in.ID), + ) + if err != nil { + return err + } + if !ok { + pterm.Info.Println("Archive cancelled") + return nil + } + } + if err := c.serviceAccounts.Delete(ctx, in.ID); err != nil { + return util.CleanedUpSdkError{Err: err} + } + pterm.Success.Printf("Archived service account: %s\n", in.ID) + return nil +} + +func printServiceAccountDetail(account *kernel.ServiceAccount) { + if account == nil { + pterm.Info.Println("Service account not found") + return + } + rows := pterm.TableData{ + {"Property", "Value"}, + {"ID", account.ID}, + {"Name", account.Name}, + {"Description", util.OrDash(account.Description)}, + {"Status", workloadIdentityResourceStatus(account.JSON.ArchivedAt.Valid())}, + {"Security Version", fmt.Sprintf("%d", account.SecurityVersion)}, + {"Created By User ID", util.OrDash(account.CreatedByUserID)}, + {"Last Used At", util.FormatLocal(account.LastUsedAt)}, + {"Archived At", util.FormatLocal(account.ArchivedAt)}, + {"Created At", util.FormatLocal(account.CreatedAt)}, + {"Updated At", util.FormatLocal(account.UpdatedAt)}, + } + PrintTableNoPad(rows, true) +} + +var serviceAccountsCmd = &cobra.Command{ + Use: "service-accounts", + Aliases: []string{"service-account"}, + Short: "Manage workload service accounts", + Long: "Manage organization-scoped service accounts used as workload identity federation targets. " + + "Reading requires a signed-in organization member; creating, updating, and archiving require credential administrator access. " + + "Kernel API keys cannot manage service accounts.", + Run: func(cmd *cobra.Command, args []string) { _ = cmd.Help() }, +} + +var serviceAccountsListCmd = &cobra.Command{ + Use: "list", + Short: "List service account records", + Long: "List service accounts in the current organization. Search matches name or description case-insensitively and matches an exact service account ID. " + + "Any signed-in organization member can read this; Kernel API keys cannot.", + Args: cobra.NoArgs, + RunE: runServiceAccountsList, +} + +var serviceAccountsGetCmd = &cobra.Command{ + Use: "get ", + Short: "Get a service account", + Long: "Get a service account by its stable resource ID. Any signed-in organization member can read this; Kernel API keys cannot.", + Args: cobra.ExactArgs(1), + RunE: runServiceAccountsGet, +} + +var serviceAccountsCreateCmd = &cobra.Command{ + Use: "create --name ", + Short: "Create a service account", + Long: "Create an organization-scoped service account. Organization credential administrator access is required; no external namespace-ownership or staff approval is required.", + Args: cobra.NoArgs, + RunE: runServiceAccountsCreate, +} + +var serviceAccountsUpdateCmd = &cobra.Command{ + Use: "update --expected-version ", + Short: "Update a service account", + Long: "Update a service account using optimistic concurrency. Pass the current security_version from get or list as --expected-version.", + Args: cobra.ExactArgs(1), + RunE: runServiceAccountsUpdate, +} + +var serviceAccountsDeleteCmd = &cobra.Command{ + Use: "delete ", + Aliases: []string{"archive"}, + Short: "Archive a service account", + Long: "Archive a service account. This retains history and invalidates associated authority within the documented status bound; it does not delete browser resources the account created.", + Args: cobra.ExactArgs(1), + RunE: runServiceAccountsDelete, +} + +func init() { + addJSONOutputFlag(serviceAccountsListCmd) + serviceAccountsListCmd.Flags().Int("page", 1, "Page number (1-based)") + serviceAccountsListCmd.Flags().Int("per-page", 20, "Items per page (1-99; default 20)") + serviceAccountsListCmd.Flags().String("query", "", "Case-insensitive search by name or description; an exact service account ID also matches (maximum 256 characters)") + serviceAccountsListCmd.Flags().String("status", "", "Filter by lifecycle status: active, archived, or all") + + addJSONOutputFlag(serviceAccountsGetCmd) + + addJSONOutputFlag(serviceAccountsCreateCmd) + serviceAccountsCreateCmd.Flags().String("name", "", "Service account name; starts with a letter or number and contains only letters, numbers, and hyphens (required)") + serviceAccountsCreateCmd.Flags().String("description", "", "Optional description (maximum 4096 characters)") + _ = serviceAccountsCreateCmd.MarkFlagRequired("name") + + addJSONOutputFlag(serviceAccountsUpdateCmd) + serviceAccountsUpdateCmd.Flags().Int64("expected-version", 0, "Current security_version used for optimistic concurrency (required)") + serviceAccountsUpdateCmd.Flags().String("name", "", "New service account name") + serviceAccountsUpdateCmd.Flags().String("description", "", "New description; pass an empty string to clear it") + _ = serviceAccountsUpdateCmd.MarkFlagRequired("expected-version") + + serviceAccountsDeleteCmd.Flags().BoolP("yes", "y", false, "Skip confirmation prompt") + + serviceAccountsCmd.AddCommand(serviceAccountsListCmd, serviceAccountsGetCmd, serviceAccountsCreateCmd, serviceAccountsUpdateCmd, serviceAccountsDeleteCmd) + rootCmd.AddCommand(serviceAccountsCmd) +} + +func getServiceAccountsHandler(cmd *cobra.Command) ServiceAccountsCmd { + client := getKernelClient(cmd) + return ServiceAccountsCmd{serviceAccounts: &client.ServiceAccounts, prompter: interactive.NewPrompter()} +} + +func runServiceAccountsList(cmd *cobra.Command, args []string) error { + page, _ := cmd.Flags().GetInt("page") + perPage, _ := cmd.Flags().GetInt("per-page") + query, _ := cmd.Flags().GetString("query") + status, _ := cmd.Flags().GetString("status") + output, _ := cmd.Flags().GetString("output") + return getServiceAccountsHandler(cmd).List(cmd.Context(), ServiceAccountsListInput{Page: page, PerPage: perPage, Query: query, Status: status, Output: output}) +} + +func runServiceAccountsGet(cmd *cobra.Command, args []string) error { + output, _ := cmd.Flags().GetString("output") + return getServiceAccountsHandler(cmd).Get(cmd.Context(), ServiceAccountsGetInput{ID: args[0], Output: output}) +} + +func runServiceAccountsCreate(cmd *cobra.Command, args []string) error { + name, _ := cmd.Flags().GetString("name") + description, _ := cmd.Flags().GetString("description") + output, _ := cmd.Flags().GetString("output") + return getServiceAccountsHandler(cmd).Create(cmd.Context(), ServiceAccountsCreateInput{Name: name, Description: description, Output: output}) +} + +func runServiceAccountsUpdate(cmd *cobra.Command, args []string) error { + expectedVersion, _ := cmd.Flags().GetInt64("expected-version") + name, _ := cmd.Flags().GetString("name") + description, _ := cmd.Flags().GetString("description") + output, _ := cmd.Flags().GetString("output") + var namePtr, descriptionPtr *string + if cmd.Flags().Changed("name") { + namePtr = &name + } + if cmd.Flags().Changed("description") { + descriptionPtr = &description + } + return getServiceAccountsHandler(cmd).Update(cmd.Context(), ServiceAccountsUpdateInput{ + ID: args[0], ExpectedVersion: expectedVersion, Name: namePtr, Description: descriptionPtr, Output: output, + }) +} + +func runServiceAccountsDelete(cmd *cobra.Command, args []string) error { + yes, _ := cmd.Flags().GetBool("yes") + return getServiceAccountsHandler(cmd).Delete(cmd.Context(), ServiceAccountsDeleteInput{ID: args[0], SkipConfirm: yes}) +} diff --git a/cmd/tasks.go b/cmd/tasks.go new file mode 100644 index 00000000..9c51a494 --- /dev/null +++ b/cmd/tasks.go @@ -0,0 +1,356 @@ +package cmd + +import ( + "context" + "fmt" + "sort" + "strings" + "time" + + "github.com/kernel/cli/pkg/util" + kernel "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + "github.com/kernel/kernel-go-sdk/packages/pagination" + "github.com/pterm/pterm" + "github.com/samber/lo" + "github.com/spf13/cobra" +) + +// TasksService defines the task SDK methods exposed by the CLI. +type TasksService interface { + New(ctx context.Context, body kernel.TaskNewParams, opts ...option.RequestOption) (*kernel.Task, error) + Get(ctx context.Context, id string, opts ...option.RequestOption) (*kernel.Task, error) + List(ctx context.Context, query kernel.TaskListParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.Task], error) + LinkBrowsers(ctx context.Context, id string, body kernel.TaskLinkBrowsersParams, opts ...option.RequestOption) (*kernel.Task, error) +} + +type TasksCmd struct { + tasks TasksService +} + +type TasksCreateInput struct { + Description string + StartedAt string + TargetWebsite string + Metadata map[string]string + SessionIDs []string + Output string +} + +type TasksGetInput struct { + ID string + Output string +} + +type TasksListInput struct { + Page int + PerPage int + SessionID string + Output string +} + +type TasksLinkBrowsersInput struct { + ID string + SessionIDs []string + Output string +} + +func normalizePageInput(page, perPage int) (int, int, error) { + if page == 0 { + page = 1 + } + if perPage == 0 { + perPage = 20 + } + if page < 1 { + return 0, 0, fmt.Errorf("--page must be at least 1") + } + // The CLI requests one extra item to determine whether another page exists; + // the API's limit is 100, so the largest display page is 99. + if perPage < 1 || perPage > 99 { + return 0, 0, fmt.Errorf("--per-page must be between 1 and 99") + } + return page, perPage, nil +} + +func printListPaginationFooter(page, perPage, itemsThisPage int, hasMore bool, nextCommand string) { + pterm.Printf("\nPage: %d Per-page: %d Items this page: %d Has more: %s\n", page, perPage, itemsThisPage, lo.Ternary(hasMore, "yes", "no")) + if hasMore { + pterm.Printf("Next: %s\n", nextCommand) + } +} + +func parseRFC3339Flag(name, value string) (time.Time, error) { + parsed, err := time.Parse(time.RFC3339, value) + if err != nil { + return time.Time{}, fmt.Errorf("%s must be an RFC3339 date-time", name) + } + return parsed, nil +} + +func formatStringMap(values map[string]string) string { + if len(values) == 0 { + return "-" + } + keys := make([]string, 0, len(values)) + for key := range values { + keys = append(keys, key) + } + sort.Strings(keys) + parts := make([]string, 0, len(keys)) + for _, key := range keys { + parts = append(parts, fmt.Sprintf("%s=%s", key, values[key])) + } + return strings.Join(parts, ", ") +} + +func (c TasksCmd) Create(ctx context.Context, in TasksCreateInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + if strings.TrimSpace(in.Description) == "" { + return fmt.Errorf("--description is required") + } + if len(in.Metadata) > 20 { + return fmt.Errorf("--metadata accepts at most 20 keys") + } + if len(in.SessionIDs) > 100 { + return fmt.Errorf("--session-id accepts at most 100 browser IDs") + } + + params := kernel.TaskNewParams{ + Description: in.Description, + Metadata: kernel.TaskMetadata(in.Metadata), + SessionIDs: in.SessionIDs, + } + if in.StartedAt != "" { + startedAt, err := parseRFC3339Flag("--started-at", in.StartedAt) + if err != nil { + return err + } + params.StartedAt = kernel.Opt(startedAt) + } + if in.TargetWebsite != "" { + params.TargetWebsite = kernel.Opt(in.TargetWebsite) + } + + task, err := c.tasks.New(ctx, params) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(task) + } + pterm.Success.Printf("Created task: %s\n", task.ID) + printTaskDetail(task) + return nil +} + +func (c TasksCmd) Get(ctx context.Context, in TasksGetInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + task, err := c.tasks.Get(ctx, in.ID) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(task) + } + printTaskDetail(task) + return nil +} + +func (c TasksCmd) List(ctx context.Context, in TasksListInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + page, perPage, err := normalizePageInput(in.Page, in.PerPage) + if err != nil { + return err + } + params := kernel.TaskListParams{ + Limit: kernel.Opt(int64(perPage + 1)), + Offset: kernel.Opt(int64((page - 1) * perPage)), + } + if in.SessionID != "" { + params.SessionID = kernel.Opt(in.SessionID) + } + + result, err := c.tasks.List(ctx, params) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + var items []kernel.Task + if result != nil { + items = result.Items + } + hasMore := len(items) > perPage + if hasMore { + items = items[:perPage] + } + if in.Output == "json" { + return util.PrintPageJSON(items, page, perPage, hasMore) + } + + if len(items) == 0 { + pterm.Info.Println("No tasks found") + } else { + rows := pterm.TableData{{"Task ID", "Description", "Target Website", "Browsers", "Started At", "Created At"}} + for _, task := range items { + rows = append(rows, []string{ + task.ID, + task.Description, + util.OrDash(task.TargetWebsite), + fmt.Sprint(len(task.SessionIDs)), + util.FormatLocal(task.StartedAt), + util.FormatLocal(task.CreatedAt), + }) + } + PrintTableNoPad(rows, true) + } + + next := fmt.Sprintf("kernel tasks list --page %d --per-page %d", page+1, perPage) + if in.SessionID != "" { + next += fmt.Sprintf(" --session-id %q", in.SessionID) + } + printListPaginationFooter(page, perPage, len(items), hasMore, next) + return nil +} + +func (c TasksCmd) LinkBrowsers(ctx context.Context, in TasksLinkBrowsersInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + if len(in.SessionIDs) == 0 { + return fmt.Errorf("at least one --session-id is required") + } + if len(in.SessionIDs) > 100 { + return fmt.Errorf("--session-id accepts at most 100 browser IDs") + } + task, err := c.tasks.LinkBrowsers(ctx, in.ID, kernel.TaskLinkBrowsersParams{SessionIDs: in.SessionIDs}) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(task) + } + pterm.Success.Printf("Linked browsers to task: %s\n", task.ID) + printTaskDetail(task) + return nil +} + +func printTaskDetail(task *kernel.Task) { + rows := pterm.TableData{ + {"Property", "Value"}, + {"ID", task.ID}, + {"Description", task.Description}, + {"Target Website", util.OrDash(task.TargetWebsite)}, + {"Metadata", formatStringMap(task.Metadata)}, + {"Browser IDs", util.OrDash(strings.Join(task.SessionIDs, ", "))}, + {"Started At", util.FormatLocal(task.StartedAt)}, + {"Created At", util.FormatLocal(task.CreatedAt)}, + } + PrintTableNoPad(rows, true) +} + +var tasksCmd = &cobra.Command{ + Use: "tasks", + Aliases: []string{"task"}, + Short: "Define tasks and link the browsers used for them", + Long: "Define goals that agents work toward, link the browsers they use, and retrieve task records for reporting.", +} + +var tasksCreateCmd = &cobra.Command{ + Use: "create", + Short: "Create a task", + Long: "Define a task before or while an agent works on it. Browsers may be linked now with --session-id or later with kernel tasks link-browsers. Submit reports against the returned task ID.", + Args: cobra.NoArgs, + RunE: runTasksCreate, +} + +var tasksGetCmd = &cobra.Command{ + Use: "get ", + Short: "Get a task and its linked browser IDs", + Args: cobra.ExactArgs(1), + RunE: runTasksGet, +} + +var tasksListCmd = &cobra.Command{ + Use: "list", + Short: "List tasks, newest first", + Long: "List tasks in the selected project, newest first. Use --session-id to show only tasks linked to one browser.", + Args: cobra.NoArgs, + RunE: runTasksList, +} + +var tasksLinkBrowsersCmd = &cobra.Command{ + Use: "link-browsers ", + Short: "Link browsers to a task", + Long: "Link one or more browsers to an existing task. Browsers already linked are ignored, so the command is safe to retry. A task can have at most 100 linked browsers.", + Args: cobra.ExactArgs(1), + RunE: runTasksLinkBrowsers, +} + +func init() { + tasksCmd.AddCommand(tasksCreateCmd, tasksGetCmd, tasksListCmd, tasksLinkBrowsersCmd) + + tasksCreateCmd.Flags().String("description", "", "What the task is meant to accomplish, at most 4 KB (required)") + tasksCreateCmd.Flags().String("started-at", "", "When work started as RFC3339; defaults to creation time and must be within 30 days past to 5 minutes future") + tasksCreateCmd.Flags().String("target-website", "", "Target website hostname without a scheme or path (maximum 253 characters)") + tasksCreateCmd.Flags().StringArray("metadata", nil, "Grouping metadata as KEY=VALUE (repeatable; at most 20 keys, keys 1-64 characters, values at most 256 characters, 4 KB total)") + tasksCreateCmd.Flags().StringSlice("session-id", nil, "Browser ID to link, including a deleted browser (repeatable; at most 100)") + _ = tasksCreateCmd.MarkFlagRequired("description") + addJSONOutputFlag(tasksCreateCmd) + + addJSONOutputFlag(tasksGetCmd) + + tasksListCmd.Flags().Int("page", 1, "Page number (1-based)") + tasksListCmd.Flags().Int("per-page", 20, "Items per page (1-99, default 20)") + tasksListCmd.Flags().String("session-id", "", "Only return tasks linked to this browser ID") + addJSONOutputFlag(tasksListCmd) + + tasksLinkBrowsersCmd.Flags().StringSlice("session-id", nil, "Browser ID to link, including a deleted browser (repeatable; 1-100 required)") + _ = tasksLinkBrowsersCmd.MarkFlagRequired("session-id") + addJSONOutputFlag(tasksLinkBrowsersCmd) +} + +func runTasksCreate(cmd *cobra.Command, args []string) error { + description, _ := cmd.Flags().GetString("description") + startedAt, _ := cmd.Flags().GetString("started-at") + targetWebsite, _ := cmd.Flags().GetString("target-website") + metadataValues, _ := cmd.Flags().GetStringArray("metadata") + metadata, err := parseStringMapFlag(metadataValues, "--metadata") + if err != nil { + return err + } + sessionIDs, _ := cmd.Flags().GetStringSlice("session-id") + output, _ := cmd.Flags().GetString("output") + client := getKernelClient(cmd) + return (TasksCmd{tasks: &client.Tasks}).Create(cmd.Context(), TasksCreateInput{ + Description: description, StartedAt: startedAt, TargetWebsite: targetWebsite, + Metadata: metadata, SessionIDs: sessionIDs, Output: output, + }) +} + +func runTasksGet(cmd *cobra.Command, args []string) error { + output, _ := cmd.Flags().GetString("output") + client := getKernelClient(cmd) + return (TasksCmd{tasks: &client.Tasks}).Get(cmd.Context(), TasksGetInput{ID: args[0], Output: output}) +} + +func runTasksList(cmd *cobra.Command, args []string) error { + page, _ := cmd.Flags().GetInt("page") + perPage, _ := cmd.Flags().GetInt("per-page") + sessionID, _ := cmd.Flags().GetString("session-id") + output, _ := cmd.Flags().GetString("output") + client := getKernelClient(cmd) + return (TasksCmd{tasks: &client.Tasks}).List(cmd.Context(), TasksListInput{Page: page, PerPage: perPage, SessionID: sessionID, Output: output}) +} + +func runTasksLinkBrowsers(cmd *cobra.Command, args []string) error { + sessionIDs, _ := cmd.Flags().GetStringSlice("session-id") + output, _ := cmd.Flags().GetString("output") + client := getKernelClient(cmd) + return (TasksCmd{tasks: &client.Tasks}).LinkBrowsers(cmd.Context(), TasksLinkBrowsersInput{ID: args[0], SessionIDs: sessionIDs, Output: output}) +} diff --git a/cmd/tasks_reports_test.go b/cmd/tasks_reports_test.go new file mode 100644 index 00000000..c555057f --- /dev/null +++ b/cmd/tasks_reports_test.go @@ -0,0 +1,212 @@ +package cmd + +import ( + "context" + "encoding/json" + "testing" + "time" + + kernel "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + "github.com/kernel/kernel-go-sdk/packages/pagination" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +type fakeTasksService struct { + newFunc func(kernel.TaskNewParams) *kernel.Task + listFunc func(kernel.TaskListParams) *pagination.OffsetPagination[kernel.Task] + linkFunc func(string, kernel.TaskLinkBrowsersParams) *kernel.Task +} + +func (f fakeTasksService) New(_ context.Context, body kernel.TaskNewParams, _ ...option.RequestOption) (*kernel.Task, error) { + return f.newFunc(body), nil +} +func (f fakeTasksService) Get(_ context.Context, id string, _ ...option.RequestOption) (*kernel.Task, error) { + return &kernel.Task{ID: id}, nil +} +func (f fakeTasksService) List(_ context.Context, query kernel.TaskListParams, _ ...option.RequestOption) (*pagination.OffsetPagination[kernel.Task], error) { + return f.listFunc(query), nil +} +func (f fakeTasksService) LinkBrowsers(_ context.Context, id string, body kernel.TaskLinkBrowsersParams, _ ...option.RequestOption) (*kernel.Task, error) { + return f.linkFunc(id, body), nil +} + +func TestTasksCreateMapsAllFields(t *testing.T) { + startedAt := "2026-09-01T12:00:00Z" + var captured kernel.TaskNewParams + service := fakeTasksService{newFunc: func(params kernel.TaskNewParams) *kernel.Task { + captured = params + parsed, _ := time.Parse(time.RFC3339, startedAt) + return &kernel.Task{ID: "task-1", Description: params.Description, StartedAt: parsed, CreatedAt: parsed} + }} + buf := capturePtermOutput(t) + err := (TasksCmd{tasks: service}).Create(context.Background(), TasksCreateInput{ + Description: "Book a hotel", StartedAt: startedAt, TargetWebsite: "booking.example", + Metadata: map[string]string{"thread_id": "thread-1"}, SessionIDs: []string{"browser-1"}, + }) + require.NoError(t, err) + assert.Equal(t, "Book a hotel", captured.Description) + assert.Equal(t, "booking.example", captured.TargetWebsite.Value) + assert.Equal(t, "thread-1", captured.Metadata["thread_id"]) + assert.Equal(t, []string{"browser-1"}, captured.SessionIDs) + assert.True(t, captured.StartedAt.Valid()) + assert.Contains(t, buf.String(), "task-1") +} + +func TestListPageUXRejectsValuesThatCannotUseLookahead(t *testing.T) { + _, _, err := normalizePageInput(1, 100) + require.ErrorContains(t, err, "between 1 and 99") + _, _, err = normalizePageInput(-1, 20) + require.ErrorContains(t, err, "--page") +} + +func TestTasksListUsesPageUXAndPreservesFilter(t *testing.T) { + var captured kernel.TaskListParams + now := time.Date(2026, 9, 1, 0, 0, 0, 0, time.UTC) + items := []kernel.Task{ + {ID: "task-1", Description: "one", StartedAt: now, CreatedAt: now}, + {ID: "task-2", Description: "two", StartedAt: now, CreatedAt: now}, + {ID: "task-3", Description: "three", StartedAt: now, CreatedAt: now}, + } + service := fakeTasksService{listFunc: func(params kernel.TaskListParams) *pagination.OffsetPagination[kernel.Task] { + captured = params + return &pagination.OffsetPagination[kernel.Task]{Items: items} + }} + buf := capturePtermOutput(t) + err := (TasksCmd{tasks: service}).List(context.Background(), TasksListInput{Page: 2, PerPage: 2, SessionID: "browser one"}) + require.NoError(t, err) + assert.Equal(t, int64(3), captured.Limit.Value) + assert.Equal(t, int64(2), captured.Offset.Value) + assert.Equal(t, "browser one", captured.SessionID.Value) + assert.Contains(t, buf.String(), "Has more: yes") + assert.Contains(t, buf.String(), `Next: kernel tasks list --page 3 --per-page 2 --session-id "browser one"`) + assert.NotContains(t, buf.String(), "task-3") +} + +type fakeReportsService struct { + newFunc func(kernel.ReportNewParams) *kernel.Report + listFunc func(kernel.ReportListParams) *pagination.OffsetPagination[kernel.Report] +} + +func (f fakeReportsService) New(_ context.Context, body kernel.ReportNewParams, _ ...option.RequestOption) (*kernel.Report, error) { + return f.newFunc(body), nil +} +func (f fakeReportsService) Get(_ context.Context, id string, _ ...option.RequestOption) (*kernel.Report, error) { + return &kernel.Report{ID: id, Data: map[string]any{}}, nil +} +func (f fakeReportsService) List(_ context.Context, query kernel.ReportListParams, _ ...option.RequestOption) (*pagination.OffsetPagination[kernel.Report], error) { + return f.listFunc(query), nil +} + +func TestReportsCreateMapsAllFields(t *testing.T) { + occurredAt := "2026-09-01T12:00:00Z" + var captured kernel.ReportNewParams + service := fakeReportsService{newFunc: func(params kernel.ReportNewParams) *kernel.Report { + captured = params + parsed, _ := time.Parse(time.RFC3339, occurredAt) + return &kernel.Report{ID: "report-1", TaskID: params.TaskID, Type: params.Type, SchemaVersion: params.SchemaVersion.Value, SessionID: params.SessionID.Value, Data: params.Data, OccurredAt: parsed, CreatedAt: parsed} + }} + buf := capturePtermOutput(t) + err := (ReportsCmd{reports: service}).Create(context.Background(), ReportsCreateInput{ + TaskID: "task-1", Type: "task.result", Data: `{"result":"succeeded","count":2}`, + OccurredAt: occurredAt, SchemaVersion: 2, SessionID: "browser-1", + }) + require.NoError(t, err) + assert.Equal(t, "task-1", captured.TaskID) + assert.Equal(t, "task.result", captured.Type) + assert.Equal(t, "succeeded", captured.Data["result"]) + assert.Equal(t, int64(2), captured.SchemaVersion.Value) + assert.Equal(t, "browser-1", captured.SessionID.Value) + assert.True(t, captured.OccurredAt.Valid()) + assert.Contains(t, buf.String(), "report-1") +} + +func TestReportsListUsesPageUXAndPreservesFilters(t *testing.T) { + var captured kernel.ReportListParams + now := time.Date(2026, 9, 1, 0, 0, 0, 0, time.UTC) + items := []kernel.Report{ + {ID: "report-1", Type: "task.result", OccurredAt: now, CreatedAt: now}, + {ID: "report-2", Type: "task.result", OccurredAt: now, CreatedAt: now}, + } + service := fakeReportsService{listFunc: func(params kernel.ReportListParams) *pagination.OffsetPagination[kernel.Report] { + captured = params + return &pagination.OffsetPagination[kernel.Report]{Items: items} + }} + buf := capturePtermOutput(t) + err := (ReportsCmd{reports: service}).List(context.Background(), ReportsListInput{TaskID: "task one", Type: "task.result", Page: 1, PerPage: 1}) + require.NoError(t, err) + assert.Equal(t, int64(2), captured.Limit.Value) + assert.Equal(t, int64(0), captured.Offset.Value) + assert.Equal(t, "task.result", captured.Type.Value) + assert.Contains(t, buf.String(), `--task-id "task one" --type "task.result"`) + assert.NotContains(t, buf.String(), "report-2") +} + +type fakeReportTypesService struct { + listFunc func(kernel.ReportTypeListParams) *pagination.OffsetPagination[kernel.ReportTypeSummary] +} + +func (f fakeReportTypesService) Get(_ context.Context, typeName string, _ ...option.RequestOption) (*kernel.ReportType, error) { + return &kernel.ReportType{Type: typeName, Schema: map[string]any{}}, nil +} +func (f fakeReportTypesService) List(_ context.Context, query kernel.ReportTypeListParams, _ ...option.RequestOption) (*pagination.OffsetPagination[kernel.ReportTypeSummary], error) { + return f.listFunc(query), nil +} + +type fakeReportTypeVersionsService struct { + getFunc func(int64, kernel.ReportTypeVersionGetParams) *kernel.ReportTypeVersion +} + +func (f fakeReportTypeVersionsService) Get(_ context.Context, version int64, query kernel.ReportTypeVersionGetParams, _ ...option.RequestOption) (*kernel.ReportTypeVersion, error) { + return f.getFunc(version, query), nil +} + +func TestReportTypesListAndVersionGet(t *testing.T) { + var listParams kernel.ReportTypeListParams + listService := fakeReportTypesService{listFunc: func(params kernel.ReportTypeListParams) *pagination.OffsetPagination[kernel.ReportTypeSummary] { + listParams = params + return &pagination.OffsetPagination[kernel.ReportTypeSummary]{Items: []kernel.ReportTypeSummary{{Type: "task.result", LatestVersion: 2, Description: "Task outcome"}}} + }} + buf := capturePtermOutput(t) + err := (ReportTypesCmd{reportTypes: listService}).List(context.Background(), ReportTypesListInput{TaskID: "task-1", Page: 1, PerPage: 20}) + require.NoError(t, err) + assert.Equal(t, "task-1", listParams.TaskID) + assert.Equal(t, int64(21), listParams.Limit.Value) + assert.Contains(t, buf.String(), "task.result") + assert.Contains(t, buf.String(), "Has more: no") + + var gotType string + var gotVersion int64 + versionService := fakeReportTypeVersionsService{getFunc: func(version int64, params kernel.ReportTypeVersionGetParams) *kernel.ReportTypeVersion { + gotType, gotVersion = params.Type, version + return &kernel.ReportTypeVersion{Type: params.Type, Version: version, Schema: map[string]any{"type": "object"}} + }} + err = (ReportTypesCmd{versions: versionService}).GetVersion(context.Background(), ReportTypeVersionsGetInput{Type: "task.result", Version: 2}) + require.NoError(t, err) + assert.Equal(t, "task.result", gotType) + assert.Equal(t, int64(2), gotVersion) +} + +func TestTasksListJSONIncludesPageMetadata(t *testing.T) { + var items []kernel.Task + require.NoError(t, json.Unmarshal([]byte(`[{"id":"task-1"},{"id":"task-2"},{"id":"task-3"}]`), &items)) + service := fakeTasksService{listFunc: func(kernel.TaskListParams) *pagination.OffsetPagination[kernel.Task] { + return &pagination.OffsetPagination[kernel.Task]{Items: items} + }} + for _, tc := range []struct { + name string + perPage int + want string + }{ + {"more pages", 2, `{"items":[{"id":"task-1"},{"id":"task-2"}],"page":3,"per_page":2,"has_more":true}`}, + {"last page", 3, `{"items":[{"id":"task-1"},{"id":"task-2"},{"id":"task-3"}],"page":3,"per_page":3,"has_more":false}`}, + } { + t.Run(tc.name, func(t *testing.T) { + out := captureStdout(t, func() { + require.NoError(t, (TasksCmd{tasks: service}).List(context.Background(), TasksListInput{Page: 3, PerPage: tc.perPage, Output: "json"})) + }) + assert.JSONEq(t, tc.want, out) + }) + } +} diff --git a/cmd/vaults.go b/cmd/vaults.go index 6d4c2e57..1978a83c 100644 --- a/cmd/vaults.go +++ b/cmd/vaults.go @@ -380,9 +380,10 @@ func (c VaultsCmd) Invoke(ctx context.Context, vault, key, operation string, par } } linkPurchase := (item.Type == "card" || item.Type == "payment_request") && item.Spec.Provider == "link" - checkoutAuthorizedPurchase := linkPurchase || (item.Type == "card" && item.Spec.Provider == "shop_pay") - if params != nil && params.Authorize != nil && !checkoutAuthorizedPurchase { - return fmt.Errorf("--browser-id and --page-url only apply to Link cards or payment_request items and Shop Pay cards; authorize was not invoked") + if params != nil && params.Authorize != nil { + if err := validateVaultAuthorizeTarget(item, linkPurchase, params.Authorize); err != nil { + return err + } } if operation == "fill" { if !linkPurchase && len(params.Fill.Fields) == 0 { @@ -469,7 +470,7 @@ func (c VaultsCmd) Invoke(ctx context.Context, vault, key, operation string, par return c.showItem(&updated, output, open) } -func (c VaultsCmd) Events(ctx context.Context, vault, key, after string, wait int64, output string) error { +func (c VaultsCmd) Events(ctx context.Context, vault, key, after string, wait int64, includeDeleted bool, output string) error { if err := validateVaultWait(wait); err != nil { return err } @@ -477,6 +478,9 @@ func (c VaultsCmd) Events(ctx context.Context, vault, key, after string, wait in if after != "" { params.After = kernel.Opt(after) } + if includeDeleted { + params.IncludeDeleted = kernel.Opt(true) + } ctx, cancel := context.WithTimeout(ctx, time.Duration(wait)*time.Second+30*time.Second) defer cancel() events, err := c.vaults.Items.Events(ctx, key, params, option.WithMaxRetries(0)) diff --git a/cmd/vaults_commands.go b/cmd/vaults_commands.go index d7e7c51c..99fa85f0 100644 --- a/cmd/vaults_commands.go +++ b/cmd/vaults_commands.go @@ -195,7 +195,7 @@ each vault has its own key; it is created on first request and may be cached.`, }} addVaultJSONOutputFlag(itemList) itemGet := &cobra.Command{Use: "get ", Short: "get item state, available operations, and requested live data", Args: cobra.ExactArgs(2), PreRunE: vaultPreRun, - Long: "get item state, available operations, provider actions, and returned AgentCard checkout aliases.\n--expand fetches live, non-persisted provider data only when the item advertises that expansion; requesting unavailable data fails rather than returning a partial item. Link user info and shipping addresses can contain personal data. use -o json to preserve null versus omitted fields.\n--wait is a single bounded server-side observation, not a retry or a guarantee of readiness.\nan item still pending after the wait is returned as-is; ready means populated for credentials, not logged in or paid.\nfor credential edits on an already-ready item, compare versions without --wait. explicitly non-sensitive text/email values are returned; sensitive values and totp seeds are omitted.\nrecovery_required stops waiting and means unresolved, not declined or expired.\n" + vaultRecoveryHelp, + Long: "get item state, available operations, provider actions, and returned AgentCard checkout aliases.\n--expand fetches live, non-persisted provider data only when the item advertises that expansion; requesting unavailable data fails rather than returning a partial item. Link user info and shipping addresses can contain personal data. use -o json to preserve null versus omitted fields.\n--wait is a single bounded server-side observation, not a retry or a guarantee of readiness.\nan item still pending after the wait is returned as-is; ready means populated for credentials, not logged in or paid.\nfor credential edits on an already-ready item, compare versions without --wait. explicitly non-sensitive text/email values are returned; sensitive values and totp seeds are omitted.\nrecovery_required stops waiting and means unresolved, not declined or expired.\na 1Password credential_account in revoking cannot be used while KERNEL keeps retrying its revoke in the background.\nfor AgentCard authorization json, amount_authority identifies the approved amount's source; agent and display_only do not prove what the processor charged. amount_verified and charged_* may be absent when there is no observed charge. charged_kind none means the checkout produced a token or payment method for a later merchant charge; inspect item events and the merchant order record.\n" + vaultRecoveryHelp, Example: " kernel vaults items get checkout wallet-1 --expand payment_methods\n kernel vaults items get checkout wallet-1 --expand link_user_info,link_shipping_addresses -o json", RunE: func(cmd *cobra.Command, args []string) error { wait, _ := cmd.Flags().GetInt64("wait") @@ -209,18 +209,25 @@ each vault has its own key; it is created on first request and may be cached.`, itemGet.Flags().Bool("open", false, "open a returned https action url; cardholder links are human-only, agents must share privately") addVaultJSONOutputFlag(itemGet) itemEvents := &cobra.Command{Use: "events ", Short: "read immutable item events without retrying payments", Args: cobra.ExactArgs(2), PreRunE: vaultPreRun, + Long: "read immutable item events without retrying payments. with --include-deleted, deleted vaults must be addressed by id and may be an item id; item ids take precedence over keys, followed by a live key and then the most recently deleted matching key. --wait is ignored for deleted items or vaults.", RunE: func(cmd *cobra.Command, args []string) error { after, _ := cmd.Flags().GetString("after") wait, _ := cmd.Flags().GetInt64("wait") - return getVaultsHandler(cmd).Events(cmd.Context(), args[0], args[1], after, wait, vaultOutput(cmd)) + includeDeleted, _ := cmd.Flags().GetBool("include-deleted") + return getVaultsHandler(cmd).Events(cmd.Context(), args[0], args[1], after, wait, includeDeleted, vaultOutput(cmd)) }} itemEvents.Flags().String("after", "", "return events after this event id (use the last id from the previous response)") + itemEvents.Flags().Bool("include-deleted", false, "also find deleted items and deleted vaults by id; may be an item id and --wait is ignored for deleted records") itemEvents.Flags().Int64("wait", 0, "long-poll once for new events (0-60 seconds)") addVaultJSONOutputFlag(itemEvents) invoke := &cobra.Command{Use: "invoke ", Short: "invoke an operation advertised by an item", Args: cobra.ExactArgs(3), PreRunE: vaultPreRun, Long: `retrieve the item and invoke only an operation listed in available_operations. collect returns a time-scoped url for the full credential form without clearing values. -authorize sends {"type":"authorize"} for payment authorization. for a Link card or +authorize sends {"type":"authorize"} for payment authorization. for a KERNEL card, add +--browser-id alone (no --page-url) to name the browser that will pay: cards whose +cardholder enters a fresh CVC on an encrypting card form try to route that browser through +the card vault's proxy as soon as the CVC is entered, so authorize before the browser opens +the payment step and wait until fill is advertised before opening it. for a Link card or payment_request, or a Shop Pay card, at the final checkout page, add --browser-id and --page-url (both or neither) to send browser_id and page_url; see provider flows below. read the operation description and follow any approval requirements before invoking. @@ -356,6 +363,11 @@ update_access_token (imported Link wallets with token_refresh=customer): --spec- 1pw_recover (credential accounts, no parameters): returns a new 1Password link that recovers a failed account connection. share it with the account owner, then run credentials connect again with the same key; never delete the item to recover. +1pw_disconnect (credential accounts, no parameters): ends the account's 1Password + connection while keeping the item so it can be linked again. fills stop immediately. + when no other vault uses the connection, KERNEL revokes it at 1Password; if the command + reports provider_revocation_pending, KERNEL keeps retrying the revoke in the background. + its credentials need new access requests after the account is linked again. never automatically retry an access request or recovery, and never delete and recreate an item to reset an uncertain outcome; stop and tell the user instead.`, Example: ` kernel vaults items invoke user-vault login collect @@ -372,6 +384,7 @@ JSON kernel vaults items invoke user-vault github 1pw_access_request_status --params '{"timeout_seconds":60}' kernel vaults items invoke user-vault github 1pw_fill --params '{"browser_id":"","page_url":"https://github.com/login"}' kernel vaults items invoke user-vault github 1pw_fill --params '{"browser_id":"","page_url":"https://github.com/login","entry_id":"","target_id":""}' + kernel vaults items invoke user-vault onepassword 1pw_disconnect kernel vaults items invoke checkout cardholder add_payment_method kernel vaults items invoke checkout cardholder add_payment_method --enrollment server kernel vaults items invoke checkout cardholder remove_payment_method --params '{"payment_method_id":""}' @@ -426,7 +439,7 @@ JSON invoke.Flags().String("spec-file", "", "operation parameters json file (use '-' for stdin; maximum 128 KiB)") invoke.MarkFlagsMutuallyExclusive("params", "spec-file") invoke.Flags().Bool("open", false, "open a returned https action url; cardholder links are human-only, agents must share privately") - invoke.Flags().String("browser-id", "", "browser session id, not a reusable name; used by Link or Shop Pay authorize (with --page-url) and passkey operations") + invoke.Flags().String("browser-id", "", "browser session id, not a reusable name; used by authorize (alone for KERNEL cards, with --page-url for Link or Shop Pay) and passkey operations") invoke.Flags().String("page-url", "", "Link or Shop Pay authorize only: exact current top-level checkout url open in --browser-id") invoke.Flags().String("field", "", "passkey field to arm, receive a registration, or disarm; arm/register require it when ambiguous, while disarm omits it to affect every field") invoke.Flags().String("enrollment", "", "add_payment_method enrollment flow: hosted (default, cardholder link) or server (issuer backend ingest url)") @@ -504,10 +517,14 @@ JSON func newVaultDeleteCommand(item bool) *cobra.Command { use, short, nargs := "delete ", "delete a vault and invalidate all its items", 1 + long := "unresolved payment operations block vault deletion. deleting a connected KERNEL wallet first blocks new payments and then removes its enrolled card. if removal fails, the wallet is kept and continues refusing payments; reconcile the original attempt with the provider or support before retrying. deleting or recreating an item does not prove that a payment did not occur. each 1Password credential account is ended the same way as deleting it; while 1Password has not confirmed a revoke, the command reports provider_revocation_pending and keeps the vault; delete the vault again later." + flagHelp := "skip confirmation prompt" if item { use, short, nargs = "delete ", "delete an item and invalidate its credential", 2 + long = "unresolved payment operations normally block item deletion, including operations on a wallet's child cards. deleting a connected KERNEL wallet first blocks new payments and then removes its enrolled card; if removal fails, the wallet is kept and continues refusing payments; reconcile the original attempt with the provider or support before retrying deletion. a Link, KERNEL, or Shop Pay card in issuance recovery_required, or an AgentCard card in recovery_required whose checkout-create response returned no authorization ID, may be explicitly abandoned by deleting that card directly; deleting its wallet or vault remains blocked until the card is deleted. deleting or recreating an item does not prove that a payment did not occur. deleting a managed-auth credential leaves its connection and saved credential unchanged. deleting a 1Password credential account stops fills immediately and, when no other vault uses the person's connection, revokes it at 1Password; until 1Password confirms, the command reports provider_revocation_pending and KERNEL keeps retrying the revoke in the background." + flagHelp = "skip confirmation prompt; Link, KERNEL, Shop Pay, or qualifying AgentCard recovery may be abandoned only by deleting the card directly after explicit user confirmation" } - cmd := &cobra.Command{Use: use, Short: short, Args: cobra.ExactArgs(nargs), PreRunE: vaultPreRun, + cmd := &cobra.Command{Use: use, Short: short, Long: long, Args: cobra.ExactArgs(nargs), PreRunE: vaultPreRun, RunE: func(cmd *cobra.Command, args []string) error { key := "" if item { @@ -516,7 +533,7 @@ func newVaultDeleteCommand(item bool) *cobra.Command { yes, _ := cmd.Flags().GetBool("yes") return getVaultsHandler(cmd).Delete(cmd.Context(), args[0], key, yes) }} - cmd.Flags().BoolP("yes", "y", false, "skip confirmation prompt; Link, KERNEL, Shop Pay, or VGS recovery may be abandoned only by deleting the card directly after explicit user confirmation") + cmd.Flags().BoolP("yes", "y", false, flagHelp) return cmd } diff --git a/cmd/vaults_credentials.go b/cmd/vaults_credentials.go index e2f79529..a7aebcd4 100644 --- a/cmd/vaults_credentials.go +++ b/cmd/vaults_credentials.go @@ -46,9 +46,14 @@ a filled or submitted form is not proof of sign-in: inspect the page afterward.` const vaultOnePasswordCredentialHelp = `1Password flow: 1. ask whose 1Password account holds the login and confirm it is in a non-shared vault. reuse that owner's connected credential_account from items list. otherwise run - credentials connect --provider 1password, share the returned - authorization url with that owner, and poll items get - --wait 60 until connected. + credentials connect --provider 1password and share both links + with that owner. the connect url is for their own device: it opens the 1Password app + on iOS or Android and the browser elsewhere, including sign-up. existing desktop + users can use the action url; after sign-up, use that url if the account is still + pending. the first link the owner approves or declines settles it and disables the + other. both expire at expires_at; after that, rerun credentials connect with the same + vault and key for fresh links. poll items get --wait 60 until + connected. 2. credentials create --spec-file with provider "1password", account (the credential_account key), and requests: version 2 with 1-5 login entries, each with the https website of a login page. use one entry unless the user needs several @@ -85,7 +90,11 @@ user before deleting and recreating the credential for at most one new request. account links: if a credential_account advertises 1pw_recover, invoke it and share the new link with the owner, then run credentials connect again with the same key. for reconnect_required or declined without 1pw_recover, ask the owner before running -credentials connect again with the same key for a new link.` +credentials connect again with the same key for a new link. to intentionally end the +connection while retaining the account item, invoke advertised 1pw_disconnect without +parameters. fills stop immediately; revoking means KERNEL is keeping the account unusable +and retrying the revoke in the background until 1Password confirms it; link the account again +before using its credentials.` const vaultOnePasswordStoredTokenHelp = `stored-token 1Password credentials (developer integrations only, separate from the flow above): a developer who already holds a 1Password broker access token and its @@ -222,14 +231,19 @@ JSON` addVaultJSONOutputFlag(cmd) group.AddCommand(cmd) } - connect := &cobra.Command{Use: "connect --provider 1password", Short: "connect a 1Password account and return its authorization url", Args: cobra.ExactArgs(2), PreRunE: vaultPreRun, + connect := &cobra.Command{Use: "connect --provider 1password", Short: "connect a 1Password account and return its authorization links", Args: cobra.ExactArgs(2), PreRunE: vaultPreRun, Long: `create a credential_account item that connects the user's 1Password account. only use this after the user chose 1Password brokered approval over KERNEL-hosted collection. -share the returned 1Password authorization url with the account owner; they sign in and -consent at 1Password, and KERNEL receives the grant. no tokens or keys are displayed. -poll items get --wait 60 until the account state is connected, then set account to -this key in credentials create. repeating the request returns a connected or -still-pending account unchanged; otherwise it starts a new authorization with a new url. +share both links returned by the command with the account owner. the connect url is for their own device: +it opens the 1Password app on iOS or Android and the browser elsewhere, including sign-up. +existing desktop users can use the action url; after sign-up, use that url if the account +is still pending. the first link the owner approves or declines settles it and disables +the other. both links expire at expires_at; after that, rerun this command with the same +vault and key for fresh links. +no tokens or keys are displayed. poll items get --wait 60 until the account state is +connected, then set account to this key in credentials create. repeating the request +returns a connected or still-pending account unchanged; otherwise it starts a new +authorization with fresh links. ` + vaultOnePasswordCredentialHelp, Example: " kernel vaults credentials connect user-vault onepassword --provider 1password", @@ -244,7 +258,7 @@ still-pending account unchanged; otherwise it starts a new authorization with a } connect.Flags().String("provider", "", "credential account provider: 1password (required)") _ = connect.MarkFlagRequired("provider") - connect.Flags().Bool("open", false, "open the returned https authorization url") + connect.Flags().Bool("open", false, "open the returned https action url on this computer; share the connect url for the owner's device") addVaultJSONOutputFlag(connect) group.AddCommand(connect) return group diff --git a/cmd/vaults_help.go b/cmd/vaults_help.go index c0b44478..1d45b87f 100644 --- a/cmd/vaults_help.go +++ b/cmd/vaults_help.go @@ -177,8 +177,27 @@ type AgentCardCardSpec = { currency: string; // three letters card_id?: string; // opaque AgentCard id, pass through unchanged; else chosen at approval checkout_origin?: string; // top-level checkout origin for autopilot matching; update omission removes it + line_items?: AgentCardLineItem[]; // 1..20 display-only cart lines; set again for each checkout; omission removes it on update + subtotal?: number; // integer minor units >= 0; requires line_items; omission removes it on update + shipping?: number; // integer minor units >= 0; requires line_items; omission removes it on update + tax?: number; // integer minor units >= 0; requires line_items; omission removes it on update + discount?: number; // integer minor units >= 0; requires line_items; omission removes it on update }; +type AgentCardLineItem = { + title: string; // nonempty product name as the store shows it + quantity: number; // integer >= 1 + unit_amount?: number; // integer minor units >= 0; price of one + amount?: number; // integer minor units >= 0; line total, shown instead of unit_amount * quantity + brand?: string; // shown beside the title + options?: string; // chosen options, e.g. "Size S · Pink" + image_url?: string; // https product image; unsupported hosts are displayed without an image +}; + +line_items and their totals are display context only: the cardholder approves the card amount +or processor charge, and a mismatched cart total does not change what they pay. they are sent +only for checkouts without prepare_checkout; prepared checkouts use the preparation context. + // one live KERNEL purchase. with payment_method_id (or the legacy default card), // authorize obtains a network token and one-time code for fill on merchant_url's exact // origin until expires_at. Mastercard purchases need no hosted approval. a Visa purchase diff --git a/cmd/vaults_link.go b/cmd/vaults_link.go index 93987029..32349bdb 100644 --- a/cmd/vaults_link.go +++ b/cmd/vaults_link.go @@ -65,7 +65,8 @@ var linkCheckoutPageURL = regexp.MustCompile(`^https://[^/?#@*\s]+(?:[/?#][^\s]* const linkAuthorizeServerErrorGuidance = "if the browser was not created with --vault for this vault, was deleted, or is a pool browser that is not leased, checkout inspection cannot run: create a browser with --vault, open the checkout in it, and authorize again with that browser's session id. otherwise re-get the item and follow its advertised operations" // parseVaultAuthorizeCheckout returns the authorize request for --browser-id and --page-url, -// or nil when neither flag is set. +// or nil when neither flag is set. --browser-id alone names the browser that will pay with a +// Kernel card; --page-url always needs --browser-id. func parseVaultAuthorizeCheckout(cmd *cobra.Command, operation string) (*kernel.AuthorizeVaultItemOperationRequestParam, error) { browserSet, pageSet := cmd.Flags().Changed("browser-id"), cmd.Flags().Changed("page-url") if !browserSet && !pageSet { @@ -81,22 +82,43 @@ func parseVaultAuthorizeCheckout(cmd *cobra.Command, operation string) (*kernel. } return nil, fmt.Errorf("--browser-id and --page-url are only supported for authorize") } - if browserSet != pageSet { - return nil, fmt.Errorf("--browser-id and --page-url must be passed together; authorize was not invoked") + if pageSet && !browserSet { + return nil, fmt.Errorf("--page-url requires --browser-id; authorize was not invoked") } browserID, _ := cmd.Flags().GetString("browser-id") - pageURL, _ := cmd.Flags().GetString("page-url") if strings.TrimSpace(browserID) == "" { return nil, fmt.Errorf("--browser-id must be a non-empty browser session ID, not a name") } - if _, err := url.Parse(pageURL); err != nil || !linkCheckoutPageURL.MatchString(pageURL) { - return nil, fmt.Errorf("--page-url must be the exact current top-level https checkout url") - } - return &kernel.AuthorizeVaultItemOperationRequestParam{ + request := &kernel.AuthorizeVaultItemOperationRequestParam{ Type: kernel.AuthorizeVaultItemOperationRequestTypeAuthorize, BrowserID: kernel.Opt(browserID), - PageURL: kernel.Opt(pageURL), - }, nil + } + if pageSet { + pageURL, _ := cmd.Flags().GetString("page-url") + if _, err := url.Parse(pageURL); err != nil || !linkCheckoutPageURL.MatchString(pageURL) { + return nil, fmt.Errorf("--page-url must be the exact current top-level https checkout url") + } + request.PageURL = kernel.Opt(pageURL) + } + return request, nil +} + +// validateVaultAuthorizeTarget checks authorize flags against the item: a KERNEL card takes +// --browser-id alone, while Link cards/payment_request items and Shop Pay cards take both flags. +func validateVaultAuthorizeTarget(item *kernel.VaultItemUnion, linkPurchase bool, authorize *kernel.AuthorizeVaultItemOperationRequestParam) error { + if item.Type == "card" && item.Spec.Provider == "kernel" { + if authorize.PageURL.Valid() { + return fmt.Errorf("KERNEL cards take --browser-id without --page-url; authorize was not invoked") + } + return nil + } + if linkPurchase || (item.Type == "card" && item.Spec.Provider == "shop_pay") { + if !authorize.PageURL.Valid() { + return fmt.Errorf("Link and Shop Pay authorize take --browser-id and --page-url together; authorize was not invoked") + } + return nil + } + return fmt.Errorf("--browser-id and --page-url only apply to KERNEL cards, Link cards or payment_request items, and Shop Pay cards; authorize was not invoked") } // linkAuthorizeError keeps the API's error code and message and adds the recovery step. diff --git a/cmd/vaults_link_test.go b/cmd/vaults_link_test.go index bfd05840..86b82a7a 100644 --- a/cmd/vaults_link_test.go +++ b/cmd/vaults_link_test.go @@ -118,17 +118,17 @@ func TestVaultLinkAuthorizeCheckoutValidation(t *testing.T) { args []string want string }{ - "browser only": {[]string{"authorize", "--browser-id", "browser-1"}, "must be passed together"}, - "page only": {[]string{"authorize", "--page-url", "https://shop.example/checkout"}, "must be passed together"}, - "blank browser": {[]string{"authorize", "--browser-id", " ", "--page-url", "https://shop.example/checkout"}, "--browser-id must be"}, - "http page": {[]string{"authorize", "--browser-id", "browser-1", "--page-url", "http://shop.example/checkout"}, "--page-url must be"}, - "relative page": {[]string{"authorize", "--browser-id", "browser-1", "--page-url", "/checkout"}, "--page-url must be"}, - "credentials page": {[]string{"authorize", "--browser-id", "browser-1", "--page-url", "https://user:pass@shop.example/"}, "--page-url must be"}, - "space in path": {[]string{"authorize", "--browser-id", "browser-1", "--page-url", "https://shop.example/check out"}, "--page-url must be"}, - "glob host": {[]string{"authorize", "--browser-id", "browser-1", "--page-url", "https://*.shop.example/checkout"}, "--page-url must be"}, - "fill": {[]string{"fill", "--params", linkPayTokenFillParams, "--browser-id", "browser-1", "--page-url", "https://shop.example/checkout"}, "only supported for authorize; pass fill inputs with --params"}, - "restart": {[]string{"restart_verification", "--browser-id", "browser-1", "--page-url", "https://shop.example/checkout"}, "--browser-id and --page-url are only supported for authorize"}, - "params": {[]string{"authorize", "--params", linkPayTokenFillParams}, "authorize takes --browser-id and --page-url"}, + "page only": {[]string{"authorize", "--page-url", "https://shop.example/checkout"}, "--page-url requires --browser-id"}, + "blank browser only": {[]string{"authorize", "--browser-id", " "}, "--browser-id must be"}, + "blank browser": {[]string{"authorize", "--browser-id", " ", "--page-url", "https://shop.example/checkout"}, "--browser-id must be"}, + "http page": {[]string{"authorize", "--browser-id", "browser-1", "--page-url", "http://shop.example/checkout"}, "--page-url must be"}, + "relative page": {[]string{"authorize", "--browser-id", "browser-1", "--page-url", "/checkout"}, "--page-url must be"}, + "credentials page": {[]string{"authorize", "--browser-id", "browser-1", "--page-url", "https://user:pass@shop.example/"}, "--page-url must be"}, + "space in path": {[]string{"authorize", "--browser-id", "browser-1", "--page-url", "https://shop.example/check out"}, "--page-url must be"}, + "glob host": {[]string{"authorize", "--browser-id", "browser-1", "--page-url", "https://*.shop.example/checkout"}, "--page-url must be"}, + "fill": {[]string{"fill", "--params", linkPayTokenFillParams, "--browser-id", "browser-1", "--page-url", "https://shop.example/checkout"}, "only supported for authorize; pass fill inputs with --params"}, + "restart": {[]string{"restart_verification", "--browser-id", "browser-1", "--page-url", "https://shop.example/checkout"}, "--browser-id and --page-url are only supported for authorize"}, + "params": {[]string{"authorize", "--params", linkPayTokenFillParams}, "authorize takes --browser-id and --page-url"}, } { t.Run(name, func(t *testing.T) { _, _, err := executeVaultCommand(t, client, append([]string{"vaults", "items", "invoke", "checkout", "order-1"}, tc.args...)...) @@ -206,6 +206,48 @@ func TestVaultLinkAuthorizeTransportErrorKeepsCause(t *testing.T) { assert.Contains(t, err.Error(), "never creates another payment request") } +func TestVaultAuthorizeBrowserTargetByProvider(t *testing.T) { + t.Setenv("KERNEL_PROJECT", "") + for _, tc := range []struct { + name string + fixture string + args []string + body string + wantErr string + }{ + {"KERNEL card browser only", kernelCardFixture, []string{"--browser-id", "browser-1"}, `{"type":"authorize","browser_id":"browser-1"}`, ""}, + {"KERNEL card rejects page url", kernelCardFixture, []string{"--browser-id", "browser-1", "--page-url", "https://shop.example/checkout"}, "", "KERNEL cards take --browser-id without --page-url"}, + {"KERNEL payment_request rejects browser", kernelPaymentRequestFixture, []string{"--browser-id", "browser-1"}, "", "only apply to KERNEL cards"}, + {"Link card requires page url", requestedCardFixture, []string{"--browser-id", "browser-1"}, "", "take --browser-id and --page-url together"}, + {"Link payment_request requires page url", linkPaymentRequestFixture, []string{"--browser-id", "browser-1"}, "", "take --browser-id and --page-url together"}, + {"Shop Pay card requires page url", shopPayCardFixture, []string{"--browser-id", "browser-1"}, "", "take --browser-id and --page-url together"}, + {"VGS card rejects browser", vgsRequestedCardFixture, []string{"--browser-id", "browser-1"}, "", "only apply to KERNEL cards"}, + } { + t.Run(tc.name, func(t *testing.T) { + posts := 0 + client := vaultTestClient(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodPost { + posts++ + body, err := io.ReadAll(r.Body) + require.NoError(t, err) + assert.JSONEq(t, tc.body, string(body)) + } + w.Header().Set("Content-Type", "application/json") + _, _ = io.WriteString(w, tc.fixture) + }) + args := append([]string{"vaults", "items", "invoke", "checkout", "order-1", "authorize", "-o", "json"}, tc.args...) + _, _, err := executeVaultCommand(t, client, args...) + if tc.wantErr != "" { + require.ErrorContains(t, err, tc.wantErr) + assert.Equal(t, 0, posts) + return + } + require.NoError(t, err) + assert.Equal(t, 1, posts) + }) + } +} + func TestVaultCheckoutInputsRequireLinkCard(t *testing.T) { t.Setenv("KERNEL_PROJECT", "") readyKernelCard := strings.Replace(strings.Replace(kernelCardFixture, `"status":"requested"`, `"status":"ready"`, 1), `{"type":"authorize","description":"Authorize this purchase"}`, `{"type":"authorize","description":"Authorize this purchase"},{"type":"fill","description":"Fill checkout fields."}`, 1) @@ -217,7 +259,7 @@ func TestVaultCheckoutInputsRequireLinkCard(t *testing.T) { _, _ = io.WriteString(w, readyKernelCard) }) _, _, err := executeVaultCommand(t, client, "vaults", "items", "invoke", "checkout", "order-1", "authorize", "--browser-id", "browser-1", "--page-url", "https://shop.example/checkout") - require.ErrorContains(t, err, "--browser-id and --page-url only apply to Link cards") + require.ErrorContains(t, err, "KERNEL cards take --browser-id without --page-url") _, _, err = executeVaultCommand(t, client, "vaults", "items", "invoke", "checkout", "order-1", "fill", "--params", linkPayTokenFillParams) require.ErrorContains(t, err, "only a Link card's fill may omit them") assert.Equal(t, 2, calls) diff --git a/cmd/vaults_onepassword_test.go b/cmd/vaults_onepassword_test.go index 55151dd6..d9b686c2 100644 --- a/cmd/vaults_onepassword_test.go +++ b/cmd/vaults_onepassword_test.go @@ -11,7 +11,7 @@ import ( "github.com/stretchr/testify/require" ) -const onePasswordAccountFixture = `{"id":"account-1","key":"onepassword","type":"credential_account","spec":{"provider":"1password","authorization":{"method":"oauth","client":{"type":"kernel_managed"}}},"state":{"provider":"1password","status":"pending_authorization"},"action":{"name":"1password_oauth","url":"https://my.1password.example/oauth/authorize?client_id=kernel&state=opaque"},"available_operations":[],"available_expansions":[],"created_at":"2026-09-01T00:00:00Z","updated_at":"2026-09-01T00:00:00Z"}` +const onePasswordAccountFixture = `{"id":"account-1","key":"onepassword","type":"credential_account","spec":{"provider":"1password","authorization":{"method":"oauth","client":{"type":"kernel_managed"}}},"state":{"provider":"1password","status":"pending_authorization"},"action":{"name":"1password_oauth","url":"https://my.1password.example/oauth/authorize?client_id=kernel&state=opaque","connect_url":"https://start.1password.example/connect?state=opaque"},"available_operations":[],"available_expansions":[],"expires_at":"2026-09-01T01:00:00Z","created_at":"2026-09-01T00:00:00Z","updated_at":"2026-09-01T00:00:00Z"}` const onePasswordCredentialFixture = `{"id":"credential-2","key":"github","type":"credential","version":1,"spec":{"provider":"1password","account":"onepassword","requests":{"version":2,"entries":[{"type":"login","parameters":{"website":"https://github.com"}}]}},"state":{"provider":"1password","status":"pending_authorization","access_request_id":"req-1","access_request":{"id":"req-1","state":"pending","identity":"never-print-identity","path":"never-print-path","has_autofill_token":false,"granted_count":0,"entries":[{"id":"entry-1","type":"login","parameters":{"website":"https://github.com"}}]}},"action":{"name":"1password_access_approval","url":"onepassword://grant-brokered-access?access_request_reference=ref-1","access_request_reference":"ref-1","instructions":"Present this link to the account owner."},"available_operations":[{"type":"1pw_access_request_status","description":"Check the request."}],"available_expansions":[],"created_at":"2026-09-01T00:00:00Z","updated_at":"2026-09-01T00:00:00Z"}` @@ -36,17 +36,43 @@ func TestCredentialConnectOnePassword(t *testing.T) { require.NoError(t, err) assert.Equal(t, 1, calls) assert.Contains(t, out, `"name": "1password_oauth"`) + assert.Contains(t, out, `"connect_url": "https://start.1password.example/connect?state=opaque"`) assert.Contains(t, out, "https://my.1password.example/oauth/authorize") _, text, err := executeVaultCommand(t, client, "vaults", "credentials", "connect", "user", "onepassword", "--provider", "1password") require.NoError(t, err) - assert.Contains(t, text, "share the 1Password authorization url with the account owner") + assert.Contains(t, text, "action url:\nhttps://my.1password.example/oauth/authorize") + assert.Contains(t, text, "1Password connect url:\nhttps://start.1password.example/connect") + assert.Contains(t, text, "share both 1Password links with the account owner") + assert.Contains(t, text, "first link the owner approves or declines settles it and disables the other") + assert.Contains(t, text, "after that, rerun credentials connect with the same vault and key for fresh links") _, _, err = executeVaultCommand(t, client, "vaults", "credentials", "connect", "user", "onepassword", "--provider", "kernel") require.ErrorContains(t, err, "--provider must be 1password") assert.Equal(t, 2, calls) } +func TestOnePasswordConnectURLMustBeDisplaySafe(t *testing.T) { + t.Setenv("KERNEL_PROJECT", "") + for _, unsafeURL := range []string{ + "javascript:alert(1)", + "https://user:secret@start.1password.example/connect", + "https://start.1password.example/connect?access_token=secret", + } { + t.Run(unsafeURL, func(t *testing.T) { + fixture := strings.Replace(onePasswordAccountFixture, "https://start.1password.example/connect?state=opaque", unsafeURL, 1) + client := vaultTestClient(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + io.WriteString(w, fixture) + }) + out, _, err := executeVaultCommand(t, client, "vaults", "items", "get", "user", "onepassword", "-o", "json") + require.NoError(t, err) + assert.NotContains(t, out, `"connect_url"`) + assert.NotContains(t, out, unsafeURL) + }) + } +} + func TestCredentialCreateOnePassword(t *testing.T) { t.Setenv("KERNEL_PROJECT", "") requests := `"requests":{"version":2,"entries":[{"type":"login","parameters":{"website":"https://github.com"},"reason":"Work account"},{"type":"login","parameters":{"website":"https://github.com"},"reason":"Personal account"}]}` @@ -143,6 +169,7 @@ func TestOnePasswordOperationRequests(t *testing.T) { {"1pw_access_request_status", `{"timeout_seconds":60}`, `{"type":"1pw_access_request_status","timeout_seconds":60}`, onePasswordCredentialFixture}, {"1pw_access_request_status", "", `{"type":"1pw_access_request_status"}`, onePasswordCredentialFixture}, {"1pw_recover", "", `{"type":"1pw_recover"}`, onePasswordAccountFixture}, + {"1pw_disconnect", "", `{"type":"1pw_disconnect"}`, onePasswordAccountFixture}, } { t.Run(tc.operation+tc.params, func(t *testing.T) { item := strings.Replace(tc.item, `"available_operations":[]`, `"available_operations":[{"type":"1pw_access_request_status","description":"x"}]`, 1) @@ -186,6 +213,7 @@ func TestOnePasswordOperationValidation(t *testing.T) { {"1pw_fill", `{"browser_id":"b","page_url":"https://github.com/login","target_id":""}`, "target_id"}, {"1pw_update_access_token", `{"access_token":"token-secret"}`, "only through --spec-file"}, {"1pw_recover", `{}`, "takes no parameters"}, + {"1pw_disconnect", `{}`, "takes no parameters"}, } { t.Run(tc.operation+tc.params, func(t *testing.T) { calls := 0 @@ -286,6 +314,14 @@ func TestCredentialHelpPresentsBothPaths(t *testing.T) { } for _, want := range []string{ "ask whose 1Password account holds the login and confirm it is in a non-shared vault", + "share both links", + "connect url is for their own device", + "opens the 1Password app", + "including sign-up", + "existing desktop", + "approves or declines settles it", + "expire at expires_at", + "after that, rerun credentials connect with the same", "1-5 login entries", "invoke 1pw_create_access_request once", "append &return_url=", @@ -317,8 +353,11 @@ func TestCredentialHelpPresentsBothPaths(t *testing.T) { assert.Contains(t, credentials.Flag("spec-file").Usage, "access_request_id/resolved") assert.NotContains(t, connect.Long, "stored-token") assert.Contains(t, connect.Long, "credential_account") + assert.Equal(t, "connect a 1Password account and return its authorization links", connect.Short) + assert.Contains(t, connect.Flag("open").Usage, "action url on this computer") + assert.Contains(t, connect.Flag("open").Usage, "connect url for the owner's device") assert.Contains(t, credentials.Example, `"provider":"1password","account":"onepassword"`) - for _, operation := range []string{"1pw_create_access_request", "1pw_access_request_status", "1pw_fill", "1pw_update_access_token", "1pw_recover"} { + for _, operation := range []string{"1pw_create_access_request", "1pw_access_request_status", "1pw_fill", "1pw_update_access_token", "1pw_recover", "1pw_disconnect"} { assert.Contains(t, invoke.Long, operation) } assert.Contains(t, invoke.Long, "--spec-file, never --params") @@ -333,6 +372,10 @@ func TestCredentialHelpPresentsBothPaths(t *testing.T) { assert.Contains(t, invoke.Long, want) } assert.Contains(t, invoke.Long, "optional access_token_expires_at (RFC3339)") + assert.Contains(t, invoke.Long, "ends the account's 1Password") + assert.Contains(t, invoke.Long, "provider_revocation_pending") + assert.Contains(t, credentials.Long, "revoking means KERNEL is keeping the account unusable") + assert.Contains(t, credentials.Long, "retrying the revoke in the background") assert.Contains(t, invoke.Long, "expiry clears the previously supplied expiry") for _, help := range []string{invoke.Long, invoke.Example, credentials.Long, credentials.Example, connect.Long} { for _, removed := range []string{"1pw_request_access", "1pw_poll_access", "1pw_reconcile", "account_id", "Family", "customer_managed", "RFC 3339"} { diff --git a/cmd/vaults_operation_params.go b/cmd/vaults_operation_params.go index 8bd7b830..cb67ffa7 100644 --- a/cmd/vaults_operation_params.go +++ b/cmd/vaults_operation_params.go @@ -32,7 +32,7 @@ func isOnePasswordOperation(operation string) bool { // vaultOperationTakesParams reports whether an operation accepts --params or --spec-file. func vaultOperationTakesParams(operation string) bool { - return operation == "fill" || operation == "webmcp_invoke" || operation == "prepare_checkout" || operation == "confirm_transaction" || operation == "remove_payment_method" || operation == "update_access_token" || (isOnePasswordOperation(operation) && operation != "1pw_recover") + return operation == "fill" || operation == "webmcp_invoke" || operation == "prepare_checkout" || operation == "confirm_transaction" || operation == "remove_payment_method" || operation == "update_access_token" || (isOnePasswordOperation(operation) && operation != "1pw_recover" && operation != "1pw_disconnect") } func applyVaultAddPaymentMethodEnrollment(operation string, params *vaultOperationParams, enrollment string, set bool) error { @@ -142,9 +142,13 @@ func parseVaultOperationParams(operation, raw string, paramsSet, openSet bool) ( }}, nil } if isOnePasswordOperation(operation) { - if operation == "1pw_recover" { + if operation == "1pw_recover" || operation == "1pw_disconnect" { if paramsSet { - return nil, fmt.Errorf("1pw_recover takes no parameters") + return nil, fmt.Errorf("%s takes no parameters", operation) + } + if operation == "1pw_disconnect" { + request := kernel.NewVaultItemPerformOperationParamsBody1pwDisconnect() + return &vaultOperationParams{OnePassword: &kernel.VaultItemPerformOperationParams{Of1pwDisconnect: &request}}, nil } return &vaultOperationParams{OnePassword: &kernel.VaultItemPerformOperationParams{Of1pwRecover: &kernel.OnePasswordRecoverVaultItemOperationRequestParam{Type: kernel.OnePasswordRecoverVaultItemOperationRequestType1pwRecover}}}, nil } diff --git a/cmd/vaults_output.go b/cmd/vaults_output.go index 5da70ae0..0944468b 100644 --- a/cmd/vaults_output.go +++ b/cmd/vaults_output.go @@ -58,7 +58,7 @@ var vaultItemFields = vaultOutputFields{ "id": nil, "key": nil, "type": nil, "version": nil, "created_at": nil, "updated_at": nil, "expires_at": nil, "description": nil, "available_operations": vaultOperationFields, "available_expansions": vaultOperationFields, - "action": vaultFieldsOf("name url expires_at instructions"), + "action": vaultFieldsOf("name url connect_url expires_at instructions"), "expanded": { "payment_methods": vaultMethodFields, "link_user_info": vaultLinkUserInfoFields, @@ -67,6 +67,7 @@ var vaultItemFields = vaultOutputFields{ "spec": { "provider": nil, "wallet": nil, "card_mode": nil, "user_id": nil, "payment_method_id": nil, "card_id": nil, "checkout_origin": nil, "amount": nil, "currency": nil, "merchant": nil, "merchant_name": nil, "merchant_url": nil, "merchant_country": nil, "merchant_category": nil, "merchant_category_code": nil, + "subtotal": nil, "shipping": nil, "tax": nil, "discount": nil, "context": nil, "expires_at": nil, "description": nil, "account": nil, "connection_id": nil, "requests": onePasswordRequestFields, "fields": vaultFieldsOf("name label type required sensitive"), @@ -76,8 +77,8 @@ var vaultItemFields = vaultOutputFields{ "totals": vaultTotalFields, "recurring": vaultFieldsOf("interval interval_count"), "line_items": { - "name": nil, "quantity": nil, "unit_amount": nil, "description": nil, - "sku": nil, "url": nil, "image_url": nil, "product_url": nil, "totals": vaultTotalFields, + "name": nil, "title": nil, "quantity": nil, "unit_amount": nil, "amount": nil, "description": nil, + "brand": nil, "options": nil, "sku": nil, "url": nil, "image_url": nil, "product_url": nil, "totals": vaultTotalFields, }, }, "state": { @@ -150,7 +151,7 @@ func filterVaultJSON(raw json.RawMessage, fields vaultOutputFields) (json.RawMes } if value, ok := object[key]; ok { isNullActionURL := key == "action_url" && bytes.Equal(bytes.TrimSpace(value), []byte("null")) - if (key == "url" || key == "approval_url" || key == "action_url" || key == "merchant_url" || key == "merchant_origin" || key == "image_url" || key == "product_url" || key == "website") && !isNullActionURL { + if (key == "url" || key == "connect_url" || key == "approval_url" || key == "action_url" || key == "merchant_url" || key == "merchant_origin" || key == "image_url" || key == "product_url" || key == "website") && !isNullActionURL { var address string if json.Unmarshal(value, &address) != nil { continue @@ -493,8 +494,39 @@ func printVaultItem(item *kernel.VaultItemUnion, output string) error { []string{"recurring interval count", intervalCount}, ) } - if item.Spec.Provider == "agentcard" && item.Spec.CheckoutOrigin != "" { - rows = append(rows, []string{"checkout origin", item.Spec.CheckoutOrigin}) + if item.Spec.Provider == "agentcard" { + if item.Spec.CheckoutOrigin != "" { + rows = append(rows, []string{"checkout origin", item.Spec.CheckoutOrigin}) + } + for i, line := range item.Spec.LineItems.OfCardVaultItemSpecAgentcardLineItems { + value := fmt.Sprintf("%s × %d", line.Title, line.Quantity) + if line.JSON.Amount.Valid() { + value += fmt.Sprintf("; line total %d", line.Amount) + } else if line.JSON.UnitAmount.Valid() { + value += fmt.Sprintf("; unit amount %d", line.UnitAmount) + } + if line.Brand != "" { + value += "; brand " + line.Brand + } + if line.Options != "" { + value += "; " + line.Options + } + rows = append(rows, []string{fmt.Sprintf("cart line %d", i+1), value}) + } + for _, total := range []struct { + label string + value int64 + present bool + }{ + {"cart subtotal", item.Spec.Subtotal, item.Spec.JSON.Subtotal.Valid()}, + {"shipping", item.Spec.Shipping, item.Spec.JSON.Shipping.Valid()}, + {"tax", item.Spec.Tax, item.Spec.JSON.Tax.Valid()}, + {"discount", item.Spec.Discount, item.Spec.JSON.Discount.Valid()}, + } { + if total.present { + rows = append(rows, []string{total.label + " (minor units)", fmt.Sprint(total.value)}) + } + } } if (item.Spec.Provider == "kernel" || item.Spec.Provider == "shop_pay" || item.Spec.Provider == "vgs") && item.Spec.MerchantURL != "" { rows = append(rows, []string{"merchant url", item.Spec.MerchantURL}) @@ -546,8 +578,24 @@ func printVaultItem(item *kernel.VaultItemUnion, output string) error { if a.Reason != "" { rows = append(rows, []string{"authorization reason", a.Reason}) } + if a.JSON.AmountAuthority.Valid() { + rows = append(rows, []string{"approved amount source", string(a.AmountAuthority)}) + } + if a.JSON.AmountVerified.Valid() { + rows = append(rows, []string{"processor amount verified", fmt.Sprint(a.AmountVerified)}) + } if a.JSON.ChargedKind.Valid() { - rows = append(rows, []string{"charged kind", string(a.ChargedKind)}, []string{"charged (minor units)", fmt.Sprintf("%d %s", a.ChargedAmountCents, a.ChargedCurrency)}) + rows = append(rows, []string{"charged kind", string(a.ChargedKind)}) + } + if a.JSON.ChargedAmountCents.Valid() || a.JSON.ChargedCurrency.Valid() { + amount, currency := "-", "-" + if a.JSON.ChargedAmountCents.Valid() { + amount = fmt.Sprint(a.ChargedAmountCents) + } + if a.JSON.ChargedCurrency.Valid() { + currency = a.ChargedCurrency + } + rows = append(rows, []string{"charged (minor units)", amount + " " + currency}) } if a.JSON.ReplayDelivered.Valid() { rows = append(rows, []string{"processor response delivered", fmt.Sprint(a.ReplayDelivered)}) @@ -583,6 +631,9 @@ func printVaultItemGuidance(item *kernel.VaultItemUnion, actions vaultItemAction if actions.RequiredAction != "" && actions.ActionURL != "" { pterm.Printf("action url:\n%s\n", actions.ActionURL) } + if actions.ConnectURL != "" { + pterm.Printf("1Password connect url:\n%s\n", actions.ConnectURL) + } if actions.ApprovalURL != "" { pterm.Printf("approval url:\n%s\n", actions.ApprovalURL) } @@ -590,8 +641,12 @@ func printVaultItemGuidance(item *kernel.VaultItemUnion, actions vaultItemAction pterm.Printf("available operation: %s — %s\n", op.Type, op.Description) } if item.Type == "credential_account" { - if actions.RequiredAction != "" { + if actions.RequiredAction != "" && actions.ConnectURL != "" { + pterm.Info.Println("share both 1Password links with the account owner. the connect url is for their own device: it opens the 1Password app on mobile and the browser elsewhere, including sign-up. existing desktop users can use the action url. after sign-up, use the action url if the account is still pending. the first link the owner approves or declines settles it and disables the other. both expire at expires_at; after that, rerun credentials connect with the same vault and key for fresh links. observe the connection with items get --wait 60; never ask for 1Password passwords or codes.") + } else if actions.RequiredAction != "" { pterm.Info.Println("share the 1Password authorization url with the account owner. observe the connection with items get --wait 60; never ask for 1Password passwords or codes.") + } else if item.State.Status == "revoking" { + pterm.Info.Println("this 1Password account cannot be used while KERNEL keeps retrying its revoke in the background. after a disconnect, link it again to use its credentials; after a delete, it is removed once 1Password confirms the revoke.") } else if item.State.Status == "reconnect_required" || item.State.Status == "declined" { pterm.Info.Println("this 1Password account is not connected. ask the owner before running credentials connect again with the same key; use 1pw_recover first if it is advertised.") } @@ -679,6 +734,8 @@ func printVaultItemGuidance(item *kernel.VaultItemUnion, actions vaultItemAction } case "shop_pay": pterm.Info.Println("Shop Pay fill never submits payment. submit checkout yourself, then report the observed merchant outcome once with confirm_transaction when advertised; reporting consumes the card whatever the outcome. never infer success or repeat an unknown checkout. " + shopPayRecoveryHelp + ".") + case "agentcard": + pterm.Info.Println("amount_authority reports where the approved amount came from: processor, agent, page, none, or display_only. agent and display_only do not prove what the processor charged. charged_kind none means checkout produced a token or payment method for a later merchant charge; absent charged fields mean the provider reported no charge information. inspect item events and the merchant's order record before deciding whether to pay again. never retry automatically; if recovery permits abandonment, delete the purchase item only after explicit user confirmation before creating a replacement.") case "vgs": switch item.State.Status { case "requested": diff --git a/cmd/vaults_output_test.go b/cmd/vaults_output_test.go index 64475ac2..1011e738 100644 --- a/cmd/vaults_output_test.go +++ b/cmd/vaults_output_test.go @@ -72,6 +72,30 @@ func TestVaultOutputAgentCardAliasesPresenceAndRedaction(t *testing.T) { assert.Contains(t, out, `"aliases": null`) } +func TestVaultOutputAgentCardCartContext(t *testing.T) { + var item kernel.VaultItemUnion + require.NoError(t, json.Unmarshal([]byte(`{ + "id":"card-id","key":"order-1","type":"card", + "spec":{"provider":"agentcard","wallet":"wallet-1","amount":1234,"currency":"usd","merchant":"Example Shop", + "line_items":[{"title":"T-shirt","quantity":2,"unit_amount":500,"amount":1000,"brand":"Acme","options":"Size S · Pink","image_url":"https://images.example/shirt.png","provider_secret":"SECRET_LINE"}], + "subtotal":1000,"shipping":150,"tax":84,"discount":0}, + "state":{"provider":"agentcard","status":"requested"}, + "available_operations":[],"available_expansions":[] + }`), &item)) + + buf := capturePtermOutput(t) + require.NoError(t, printVaultItem(&item, "")) + for _, want := range []string{"cart line 1", "T-shirt × 2", "line total 1000", "brand Acme", "Size S · Pink", "cart subtotal", "shipping", "tax", "discount"} { + assert.Contains(t, buf.String(), want) + } + + out := captureStdout(t, func() { require.NoError(t, printVaultItem(&item, "json")) }) + for _, want := range []string{`"title": "T-shirt"`, `"quantity": 2`, `"unit_amount": 500`, `"amount": 1000`, `"brand": "Acme"`, `"options": "Size S · Pink"`, `"subtotal": 1000`, `"shipping": 150`, `"tax": 84`, `"discount": 0`} { + assert.Contains(t, out, want) + } + assert.NotContains(t, out, "SECRET_LINE") +} + func TestVaultOutputLinkHasNoAliases(t *testing.T) { for _, fixture := range []string{requestedCardFixture, readyLinkCardFixture} { var item kernel.VaultItemUnion @@ -169,14 +193,15 @@ func TestVaultOutputAgentCardAuthorizationIsNotPaymentSuccess(t *testing.T) { require.NoError(t, json.Unmarshal([]byte(`{ "id":"card-id","key":"order-1","type":"card", "spec":{"provider":"agentcard","wallet":"wallet-1","amount":1234,"currency":"usd","merchant":"Example Shop"}, - "state":{"provider":"agentcard","status":"ready","authorization":{"id":"cauth_test","status":"declined","psp":"stripe","merchant":"Example Shop","amount_cents":1234,"currency":"usd","reason":"expired","charged_kind":"none","replay_delivered":false,"raw_response":"SECRET_RESPONSE"}}, + "state":{"provider":"agentcard","status":"ready","authorization":{"id":"cauth_test","status":"declined","psp":"stripe","merchant":"Example Shop","amount_cents":1234,"currency":"usd","reason":"expired","amount_authority":"agent","amount_verified":false,"charged_kind":"none","replay_delivered":false,"raw_response":"SECRET_RESPONSE"}}, "available_operations":[],"available_expansions":[] }`), &item)) buf := capturePtermOutput(t) require.NoError(t, printVaultItem(&item, "")) - for _, text := range []string{"authorization status", "declined", "expired", "charged kind", "none", "processor response delivered", "false"} { + for _, text := range []string{"authorization status", "declined", "expired", "approved amount source", "agent", "processor amount verified", "charged kind", "none", "processor response delivered", "false"} { assert.Contains(t, buf.String(), text) } + assert.NotContains(t, buf.String(), "charged (minor units)") assert.NotContains(t, buf.String(), "SECRET_RESPONSE") out := captureStdout(t, func() { require.NoError(t, printVaultItem(&item, "json")) }) assert.NotContains(t, out, `"test"`) diff --git a/cmd/vaults_payment_help_test.go b/cmd/vaults_payment_help_test.go index 1e05fa22..d332717e 100644 --- a/cmd/vaults_payment_help_test.go +++ b/cmd/vaults_payment_help_test.go @@ -28,7 +28,14 @@ func TestVaultPaymentHelpProviderBoundaries(t *testing.T) { { name: "items get", path: []string{"items", "get"}, - want: []string{"returned AgentCard checkout aliases", "not logged in or paid"}, + want: []string{ + "returned AgentCard checkout aliases", + "not logged in or paid", + "credential_account in revoking", + "amount_authority identifies the approved amount's source", + "amount_verified and charged_* may be absent", + "charged_kind none means the checkout produced a token or payment method", + }, }, { name: "items invoke", @@ -74,3 +81,24 @@ func TestVaultPaymentHelpProviderBoundaries(t *testing.T) { }) } } + +func TestVaultDeletionAndDeletedEventHelp(t *testing.T) { + vaultDelete, _, err := newVaultsCommand().Find([]string{"delete"}) + require.NoError(t, err) + assert.Contains(t, vaultDelete.Long, "each 1Password credential account is ended") + assert.Contains(t, vaultDelete.Long, "provider_revocation_pending") + assert.Contains(t, vaultDelete.Long, "delete the vault again later") + + itemDelete, _, err := newVaultsCommand().Find([]string{"items", "delete"}) + require.NoError(t, err) + assert.Contains(t, itemDelete.Long, "AgentCard card in recovery_required") + assert.Contains(t, itemDelete.Long, "deleting a managed-auth credential") + assert.Contains(t, itemDelete.Long, "deleting a 1Password credential account stops fills immediately") + assert.Contains(t, itemDelete.Flags().Lookup("yes").Usage, "qualifying AgentCard recovery") + + events, _, err := newVaultsCommand().Find([]string{"items", "events"}) + require.NoError(t, err) + assert.Contains(t, events.Long, "deleted vaults must be addressed by id") + assert.Contains(t, events.Long, "item ids take precedence over keys") + assert.Contains(t, events.Flags().Lookup("include-deleted").Usage, "--wait is ignored") +} diff --git a/cmd/vaults_policy.go b/cmd/vaults_policy.go index 151b573e..7be1b2dd 100644 --- a/cmd/vaults_policy.go +++ b/cmd/vaults_policy.go @@ -16,6 +16,7 @@ type vaultItemActions struct { RecoveryRequired bool RequiredAction string ActionURL string + ConnectURL string ApprovalURL string Operations []vaultItemOperation } @@ -53,6 +54,7 @@ func effectiveVaultItemActions(item *kernel.VaultItemUnion) (vaultItemActions, e return vaultItemActions{ RequiredAction: item.Action.Name, ActionURL: item.Action.URL, + ConnectURL: item.Action.ConnectURL, ApprovalURL: approvalURL, Operations: fields.Operations, }, nil diff --git a/cmd/vaults_test.go b/cmd/vaults_test.go index c14ac2f3..75edff03 100644 --- a/cmd/vaults_test.go +++ b/cmd/vaults_test.go @@ -283,14 +283,14 @@ func TestVaultCardRequestMapping(t *testing.T) { if provider == "link" { assert.JSONEq(t, fmt.Sprintf(`{"provider":"link","wallet":"wallet-1","amount":1234,"currency":"USD","merchant_name":"Example Shop","merchant_url":"https://shop.example","payment_method_id":"pm-1","context":%q}`, strings.Repeat("Purchase purpose. ", 7)), string(body["spec"])) } else { - assert.JSONEq(t, `{"provider":"agentcard","wallet":"wallet-1","amount":1234,"currency":"usd","merchant":"Example Shop","card_id":"vc_chosen","checkout_origin":"https://shop.example.com"}`, string(body["spec"])) + assert.JSONEq(t, `{"provider":"agentcard","wallet":"wallet-1","amount":1234,"currency":"usd","merchant":"Example Shop","card_id":"vc_chosen","checkout_origin":"https://shop.example.com","line_items":[{"title":"T-shirt","quantity":2,"unit_amount":500,"amount":1000,"brand":"Acme","options":"Size S · Pink","image_url":"https://images.example/shirt.png"}],"subtotal":1000,"shipping":150,"tax":84,"discount":0}`, string(body["spec"])) } w.Header().Set("Content-Type", "application/json") _, _ = io.WriteString(w, requestedCardFixture) }) flags := linkCardArgs() if provider == "agentcard" { - flags = []string{"--provider", provider, "--spec", `{"wallet":"wallet-1","amount":1234,"currency":"usd","merchant":"Example Shop","card_id":"vc_chosen","checkout_origin":"https://shop.example.com"}`} + flags = []string{"--provider", provider, "--spec", `{"wallet":"wallet-1","amount":1234,"currency":"usd","merchant":"Example Shop","card_id":"vc_chosen","checkout_origin":"https://shop.example.com","line_items":[{"title":"T-shirt","quantity":2,"unit_amount":500,"amount":1000,"brand":"Acme","options":"Size S · Pink","image_url":"https://images.example/shirt.png"}],"subtotal":1000,"shipping":150,"tax":84,"discount":0}`} } args := append([]string{"vaults", "cards", operation, "checkout", "order-1", "-o", "json"}, flags...) out, human, err := executeVaultCommand(t, client, args...) @@ -470,6 +470,7 @@ func TestVaultGetWaitExpansionAndEvents(t *testing.T) { case "/vaults/checkout/items/order-1/events": assert.Equal(t, "60", r.URL.Query().Get("wait")) assert.Equal(t, "event-before", r.URL.Query().Get("after")) + assert.Equal(t, "true", r.URL.Query().Get("include_deleted")) _, _ = io.WriteString(w, `[{"id":"event-next","name":"payment_failed","browser_id":"browser-1","created_at":"2026-09-01T00:00:00Z","data":{"reason":"declined","outcome_reason":"provider_error","provider_http_status":402,"provider_decline_code":"insufficient_funds","actual_currency":"usd","provider_response":{"card_number":"SECRET"}}}]`) default: t.Errorf("unexpected request: %s", r.URL) @@ -478,7 +479,7 @@ func TestVaultGetWaitExpansionAndEvents(t *testing.T) { out, _, err := executeVaultCommand(t, client, "vaults", "items", "get", "checkout", "wallet-1", "--wait", "60", "--expand", "payment_methods", "-o", "json") require.NoError(t, err) assert.JSONEq(t, connectedWalletFixture, out) - args := []string{"vaults", "items", "events", "checkout", "order-1", "--wait", "60", "--after", "event-before"} + args := []string{"vaults", "items", "events", "checkout", "order-1", "--wait", "60", "--after", "event-before", "--include-deleted"} out, _, err = executeVaultCommand(t, client, append(args, "-o", "json")...) require.NoError(t, err) assert.NotContains(t, out, "SECRET") diff --git a/cmd/workload_identity_authentication_events.go b/cmd/workload_identity_authentication_events.go new file mode 100644 index 00000000..d86ca024 --- /dev/null +++ b/cmd/workload_identity_authentication_events.go @@ -0,0 +1,203 @@ +package cmd + +import ( + "context" + "fmt" + + "github.com/kernel/cli/pkg/util" + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + "github.com/kernel/kernel-go-sdk/packages/pagination" + "github.com/pterm/pterm" + "github.com/spf13/cobra" +) + +// WorkloadIdentityAuthenticationEventsService is the subset of the SDK service used by the CLI. +type WorkloadIdentityAuthenticationEventsService interface { + List(ctx context.Context, query kernel.WorkloadIdentityAuthenticationEventListParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.WorkloadIdentityAuthenticationEvent], error) +} + +type WorkloadIdentityAuthenticationEventsCmd struct { + events WorkloadIdentityAuthenticationEventsService +} + +type WorkloadIdentityAuthenticationEventsListInput struct { + Page int + PerPage int + IssuerID string + FederationRuleID string + ServiceAccountID string + ProjectID string + Outcome string + StartTime string + EndTime string + Output string +} + +func (c WorkloadIdentityAuthenticationEventsCmd) List(ctx context.Context, in WorkloadIdentityAuthenticationEventsListInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + page, perPage, err := normalizePageInput(in.Page, in.PerPage) + if err != nil { + return err + } + params := kernel.WorkloadIdentityAuthenticationEventListParams{ + Limit: kernel.Opt(int64(perPage + 1)), + Offset: kernel.Opt(int64((page - 1) * perPage)), + } + if in.IssuerID != "" { + params.IssuerID = kernel.Opt(in.IssuerID) + } + if in.FederationRuleID != "" { + params.FederationRuleID = kernel.Opt(in.FederationRuleID) + } + if in.ServiceAccountID != "" { + params.ServiceAccountID = kernel.Opt(in.ServiceAccountID) + } + if in.ProjectID != "" { + params.ProjectID = kernel.Opt(in.ProjectID) + } + if in.Outcome != "" { + switch in.Outcome { + case string(kernel.WorkloadIdentityAuthenticationEventListParamsOutcomeSuccess): + params.Outcome = kernel.WorkloadIdentityAuthenticationEventListParamsOutcomeSuccess + case string(kernel.WorkloadIdentityAuthenticationEventListParamsOutcomeFailure): + params.Outcome = kernel.WorkloadIdentityAuthenticationEventListParamsOutcomeFailure + default: + return fmt.Errorf("invalid --outcome %q: must be one of success, failure", in.Outcome) + } + } + if in.StartTime != "" { + startTime, err := parseRFC3339Flag("--start-time", in.StartTime) + if err != nil { + return err + } + params.StartTime = kernel.Opt(startTime) + } + if in.EndTime != "" { + endTime, err := parseRFC3339Flag("--end-time", in.EndTime) + if err != nil { + return err + } + params.EndTime = kernel.Opt(endTime) + } + + result, err := c.events.List(ctx, params) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + items := []kernel.WorkloadIdentityAuthenticationEvent{} + if result != nil { + items = result.Items + } + hasMore := len(items) > perPage + if hasMore { + items = items[:perPage] + } + + if in.Output == "json" { + return util.PrintPageJSON(items, page, perPage, hasMore) + } + if len(items) == 0 { + pterm.Info.Println("No workload identity authentication events found") + } else { + rows := pterm.TableData{{"Created At", "Outcome", "Reason", "Service Account ID", "Project ID", "Issuer ID", "Rule ID", "Credential ID", "Correlation ID"}} + for _, event := range items { + rows = append(rows, []string{ + util.FormatLocal(event.CreatedAt), + string(event.Outcome), + util.OrDash(event.Reason), + event.ServiceAccountID, + event.ProjectID, + event.IssuerID, + event.FederationRuleID, + util.OrDash(event.CredentialID), + event.CorrelationID, + }) + } + PrintTableNoPad(rows, true) + } + + filters := "" + if in.IssuerID != "" { + filters += fmt.Sprintf(" --issuer-id %q", in.IssuerID) + } + if in.FederationRuleID != "" { + filters += fmt.Sprintf(" --federation-rule-id %q", in.FederationRuleID) + } + if in.ServiceAccountID != "" { + filters += fmt.Sprintf(" --service-account-id %q", in.ServiceAccountID) + } + if in.ProjectID != "" { + filters += fmt.Sprintf(" --project-id %q", in.ProjectID) + } + if in.Outcome != "" { + filters += fmt.Sprintf(" --outcome %s", in.Outcome) + } + if in.StartTime != "" { + filters += fmt.Sprintf(" --start-time %q", in.StartTime) + } + if in.EndTime != "" { + filters += fmt.Sprintf(" --end-time %q", in.EndTime) + } + nextCommand := fmt.Sprintf("kernel workload-identity authentication-events list --page %d --per-page %d%s", page+1, perPage, filters) + printListPaginationFooter(page, perPage, len(items), hasMore, nextCommand) + return nil +} + +var workloadIdentityAuthenticationEventsCmd = &cobra.Command{ + Use: "authentication-events", + Aliases: []string{"authentication-event", "events", "event"}, + Short: "Inspect workload identity authentication outcomes", + Long: "List sanitized workload identity authentication outcomes. Assertions, tokens, and arbitrary claims are never returned. " + + "Any signed-in organization member can read these events; Kernel API keys cannot.", + Run: func(cmd *cobra.Command, args []string) { _ = cmd.Help() }, +} + +var workloadIdentityAuthenticationEventsListCmd = &cobra.Command{ + Use: "list", + Short: "List sanitized workload authentication outcomes", + Long: "List authentication events without assertions, tokens, or arbitrary claims. Any signed-in organization member can read this; Kernel API keys cannot.", + Args: cobra.NoArgs, + RunE: runWorkloadIdentityAuthenticationEventsList, +} + +func init() { + addJSONOutputFlag(workloadIdentityAuthenticationEventsListCmd) + workloadIdentityAuthenticationEventsListCmd.Flags().Int("page", 1, "Page number (1-based)") + workloadIdentityAuthenticationEventsListCmd.Flags().Int("per-page", 20, "Items per page (1-99; default 20)") + workloadIdentityAuthenticationEventsListCmd.Flags().String("issuer-id", "", "Filter by exact issuer ID") + workloadIdentityAuthenticationEventsListCmd.Flags().String("federation-rule-id", "", "Filter by exact federation rule ID") + workloadIdentityAuthenticationEventsListCmd.Flags().String("service-account-id", "", "Filter by exact service account ID") + workloadIdentityAuthenticationEventsListCmd.Flags().String("project-id", "", "Filter by exact project ID") + workloadIdentityAuthenticationEventsListCmd.Flags().String("outcome", "", "Filter by outcome: success or failure") + workloadIdentityAuthenticationEventsListCmd.Flags().String("start-time", "", "Include events at or after this RFC3339 date-time") + workloadIdentityAuthenticationEventsListCmd.Flags().String("end-time", "", "Include events at or before this RFC3339 date-time") + + workloadIdentityAuthenticationEventsCmd.AddCommand(workloadIdentityAuthenticationEventsListCmd) + workloadIdentityCmd.AddCommand(workloadIdentityAuthenticationEventsCmd) +} + +func getWorkloadIdentityAuthenticationEventsHandler(cmd *cobra.Command) WorkloadIdentityAuthenticationEventsCmd { + client := getKernelClient(cmd) + return WorkloadIdentityAuthenticationEventsCmd{events: &client.WorkloadIdentityAuthenticationEvents} +} + +func runWorkloadIdentityAuthenticationEventsList(cmd *cobra.Command, args []string) error { + page, _ := cmd.Flags().GetInt("page") + perPage, _ := cmd.Flags().GetInt("per-page") + issuerID, _ := cmd.Flags().GetString("issuer-id") + federationRuleID, _ := cmd.Flags().GetString("federation-rule-id") + serviceAccountID, _ := cmd.Flags().GetString("service-account-id") + projectID, _ := cmd.Flags().GetString("project-id") + outcome, _ := cmd.Flags().GetString("outcome") + startTime, _ := cmd.Flags().GetString("start-time") + endTime, _ := cmd.Flags().GetString("end-time") + output, _ := cmd.Flags().GetString("output") + return getWorkloadIdentityAuthenticationEventsHandler(cmd).List(cmd.Context(), WorkloadIdentityAuthenticationEventsListInput{ + Page: page, PerPage: perPage, IssuerID: issuerID, FederationRuleID: federationRuleID, + ServiceAccountID: serviceAccountID, ProjectID: projectID, Outcome: outcome, + StartTime: startTime, EndTime: endTime, Output: output, + }) +} diff --git a/cmd/workload_identity_common.go b/cmd/workload_identity_common.go new file mode 100644 index 00000000..4d115a48 --- /dev/null +++ b/cmd/workload_identity_common.go @@ -0,0 +1,63 @@ +package cmd + +import ( + "fmt" + "regexp" + "strings" + + "github.com/spf13/cobra" +) + +var workloadIdentityNamePattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9-]*$`) + +var workloadIdentityCmd = &cobra.Command{ + Use: "workload-identity", + Aliases: []string{"workload-identities"}, + Short: "Manage workload identity federation", + Long: "Manage trusted workload identity issuers, federation rules, and authentication events. " + + "These commands require a signed-in organization member; Kernel API keys cannot manage workload identity resources.", + Run: func(cmd *cobra.Command, args []string) { + _ = cmd.Help() + }, +} + +func init() { + rootCmd.AddCommand(workloadIdentityCmd) +} + +func validateWorkloadIdentityName(value, flagName string) (string, error) { + value = strings.TrimSpace(value) + if value == "" { + return "", fmt.Errorf("--%s is required", flagName) + } + if len(value) > 128 { + return "", fmt.Errorf("--%s must be at most 128 characters", flagName) + } + if !workloadIdentityNamePattern.MatchString(value) { + return "", fmt.Errorf("--%s must start with a letter or number and contain only letters, numbers, and hyphens", flagName) + } + return value, nil +} + +func validateWorkloadIdentityDescription(value string) error { + if len(value) > 4096 { + return fmt.Errorf("--description must be at most 4096 characters") + } + return nil +} + +func validateWorkloadIdentityListStatus(value string) (string, error) { + switch value { + case "", "active", "archived", "all": + return value, nil + default: + return "", fmt.Errorf("invalid --status %q: must be one of active, archived, all", value) + } +} + +func workloadIdentityResourceStatus(archived bool) string { + if archived { + return "archived" + } + return "active" +} diff --git a/cmd/workload_identity_federation_rules.go b/cmd/workload_identity_federation_rules.go new file mode 100644 index 00000000..e9acd2f4 --- /dev/null +++ b/cmd/workload_identity_federation_rules.go @@ -0,0 +1,868 @@ +package cmd + +import ( + "context" + "fmt" + "regexp" + "strings" + + "github.com/kernel/cli/pkg/interactive" + "github.com/kernel/cli/pkg/util" + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + "github.com/kernel/kernel-go-sdk/packages/pagination" + "github.com/pterm/pterm" + "github.com/spf13/cobra" +) + +// WorkloadIdentityFederationRulesService is the subset of the SDK service used by the CLI. +type WorkloadIdentityFederationRulesService interface { + New(ctx context.Context, body kernel.WorkloadIdentityFederationRuleNewParams, opts ...option.RequestOption) (*kernel.WorkloadIdentityFederationRule, error) + Get(ctx context.Context, id string, opts ...option.RequestOption) (*kernel.WorkloadIdentityFederationRule, error) + Update(ctx context.Context, id string, body kernel.WorkloadIdentityFederationRuleUpdateParams, opts ...option.RequestOption) (*kernel.WorkloadIdentityFederationRule, error) + List(ctx context.Context, query kernel.WorkloadIdentityFederationRuleListParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.WorkloadIdentityFederationRule], error) + Delete(ctx context.Context, id string, opts ...option.RequestOption) error +} + +type WorkloadIdentityFederationRulesCmd struct { + rules WorkloadIdentityFederationRulesService + prompter interactive.Prompter +} + +type WorkloadIdentityFederationRulesListInput struct { + Page int + PerPage int + IssuerID string + ProjectID string + Query string + ServiceAccountID string + Status string + Output string +} + +type WorkloadIdentityFederationRuleGetInput struct { + ID string + Output string +} + +type WorkloadIdentityMatchInput struct { + Set bool + Type string + Subject *string + SubjectPrefix *string + Claims map[string]string + ClaimsSet bool + Repository *string + RepositoryID *string + RepositoryOwnerID *string + Workflow *string + WorkflowRef *string + JobWorkflowRef *string + Ref *string + Environment *string + EventNames []string + EventNamesSet bool + Namespace *string + ServiceAccount *string +} + +type WorkloadIdentityAuthorizationInput struct { + Set bool + ProjectID string + Policy string + PolicySet bool + TokenAudience string + MaxTokenTTLSeconds Int64Flag +} + +type WorkloadIdentityFederationRuleCreateInput struct { + Name string + Description string + IssuerID string + ExpectedAudience string + Enabled BoolFlag + Match WorkloadIdentityMatchInput + ServiceAccountID string + Authorization WorkloadIdentityAuthorizationInput + Output string +} + +type WorkloadIdentityFederationRuleUpdateInput struct { + ID string + ExpectedVersion int64 + Name *string + Description *string + IssuerID *string + ExpectedAudience *string + Enabled BoolFlag + Match WorkloadIdentityMatchInput + ServiceAccountID *string + Authorization WorkloadIdentityAuthorizationInput + Output string +} + +type WorkloadIdentityFederationRuleDeleteInput struct { + ID string + SkipConfirm bool +} + +func (c WorkloadIdentityFederationRulesCmd) List(ctx context.Context, in WorkloadIdentityFederationRulesListInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + page, perPage, err := normalizePageInput(in.Page, in.PerPage) + if err != nil { + return err + } + status, err := validateWorkloadIdentityListStatus(in.Status) + if err != nil { + return err + } + if len(in.Query) > 256 { + return fmt.Errorf("--query must be at most 256 characters") + } + + params := kernel.WorkloadIdentityFederationRuleListParams{ + Limit: kernel.Opt(int64(perPage + 1)), + Offset: kernel.Opt(int64((page - 1) * perPage)), + } + if in.IssuerID != "" { + params.IssuerID = kernel.Opt(in.IssuerID) + } + if in.ProjectID != "" { + params.ProjectID = kernel.Opt(in.ProjectID) + } + if in.Query != "" { + params.Query = kernel.Opt(in.Query) + } + if in.ServiceAccountID != "" { + params.ServiceAccountID = kernel.Opt(in.ServiceAccountID) + } + if status != "" { + params.Status = kernel.WorkloadIdentityFederationRuleListParamsStatus(status) + } + + result, err := c.rules.List(ctx, params) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + items := []kernel.WorkloadIdentityFederationRule{} + if result != nil { + items = result.Items + } + hasMore := len(items) > perPage + if hasMore { + items = items[:perPage] + } + + if in.Output == "json" { + return util.PrintPageJSON(items, page, perPage, hasMore) + } + if len(items) == 0 { + pterm.Info.Println("No workload identity federation rules found") + } else { + rows := pterm.TableData{{"ID", "Name", "Issuer ID", "Service Account ID", "Project ID", "Enabled", "Status", "Last Exchange At"}} + for _, rule := range items { + rows = append(rows, []string{ + rule.ID, + rule.Name, + rule.IssuerID, + rule.Target.ServiceAccountID, + rule.Authorization.ProjectID, + fmt.Sprintf("%t", rule.Enabled), + workloadIdentityResourceStatus(rule.JSON.ArchivedAt.Valid()), + util.FormatLocal(rule.LastExchangeAt), + }) + } + PrintTableNoPad(rows, true) + } + + filters := "" + if in.IssuerID != "" { + filters += fmt.Sprintf(" --issuer-id %q", in.IssuerID) + } + if in.ProjectID != "" { + filters += fmt.Sprintf(" --project-id %q", in.ProjectID) + } + if in.Query != "" { + filters += fmt.Sprintf(" --query %q", in.Query) + } + if in.ServiceAccountID != "" { + filters += fmt.Sprintf(" --service-account-id %q", in.ServiceAccountID) + } + if status != "" { + filters += fmt.Sprintf(" --status %s", status) + } + nextCommand := fmt.Sprintf("kernel workload-identity federation-rules list --page %d --per-page %d%s", page+1, perPage, filters) + printListPaginationFooter(page, perPage, len(items), hasMore, nextCommand) + return nil +} + +func (c WorkloadIdentityFederationRulesCmd) Get(ctx context.Context, in WorkloadIdentityFederationRuleGetInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + rule, err := c.rules.Get(ctx, in.ID) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(rule) + } + printWorkloadIdentityFederationRuleDetail(rule) + return nil +} + +func (c WorkloadIdentityFederationRulesCmd) Create(ctx context.Context, in WorkloadIdentityFederationRuleCreateInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + name, err := validateWorkloadIdentityName(in.Name, "name") + if err != nil { + return err + } + if err := validateWorkloadIdentityDescription(in.Description); err != nil { + return err + } + if err := validateRequiredBoundedString("--issuer-id", in.IssuerID, 128); err != nil { + return err + } + if err := validateRequiredBoundedString("--expected-audience", in.ExpectedAudience, 2048); err != nil { + return err + } + if err := validateRequiredBoundedString("--service-account-id", in.ServiceAccountID, 128); err != nil { + return err + } + match, set, err := buildWorkloadIdentityMatch(in.Match) + if err != nil { + return err + } + if !set { + return fmt.Errorf("--match-type is required") + } + authorization, set, err := buildWorkloadIdentityAuthorization(in.Authorization) + if err != nil { + return err + } + if !set { + return fmt.Errorf("--project-id, --policy, and --token-audience are required") + } + + config := kernel.WorkloadIdentityFederationRuleConfigParam{ + Name: name, + IssuerID: in.IssuerID, + ExpectedAudience: in.ExpectedAudience, + Match: match, + Target: kernel.WorkloadIdentityTargetParam{ + Type: kernel.WorkloadIdentityTargetTypeServiceAccount, + ServiceAccountID: in.ServiceAccountID, + }, + Authorization: authorization, + } + if in.Description != "" { + config.Description = kernel.Opt(in.Description) + } + if in.Enabled.Set { + config.Enabled = kernel.Opt(in.Enabled.Value) + } + + rule, err := c.rules.New(ctx, kernel.WorkloadIdentityFederationRuleNewParams{WorkloadIdentityFederationRuleConfig: config}) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(rule) + } + pterm.Success.Printf("Created workload identity federation rule: %s\n", rule.ID) + printWorkloadIdentityFederationRuleDetail(rule) + return nil +} + +func (c WorkloadIdentityFederationRulesCmd) Update(ctx context.Context, in WorkloadIdentityFederationRuleUpdateInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + if in.ExpectedVersion < 1 { + return fmt.Errorf("--expected-version must be at least 1") + } + params := kernel.WorkloadIdentityFederationRuleUpdateParams{ExpectedVersion: in.ExpectedVersion} + changed := false + if in.Name != nil { + name, err := validateWorkloadIdentityName(*in.Name, "name") + if err != nil { + return err + } + params.Name = kernel.Opt(name) + changed = true + } + if in.Description != nil { + if err := validateWorkloadIdentityDescription(*in.Description); err != nil { + return err + } + params.Description = kernel.Opt(*in.Description) + changed = true + } + if in.IssuerID != nil { + if err := validateRequiredBoundedString("--issuer-id", *in.IssuerID, 128); err != nil { + return err + } + params.IssuerID = kernel.Opt(*in.IssuerID) + changed = true + } + if in.ExpectedAudience != nil { + if err := validateRequiredBoundedString("--expected-audience", *in.ExpectedAudience, 2048); err != nil { + return err + } + params.ExpectedAudience = kernel.Opt(*in.ExpectedAudience) + changed = true + } + if in.Enabled.Set { + params.Enabled = kernel.Opt(in.Enabled.Value) + changed = true + } + match, set, err := buildWorkloadIdentityMatch(in.Match) + if err != nil { + return err + } + if set { + params.Match = match + changed = true + } + if in.ServiceAccountID != nil { + if err := validateRequiredBoundedString("--service-account-id", *in.ServiceAccountID, 128); err != nil { + return err + } + params.Target = kernel.WorkloadIdentityTargetParam{ + Type: kernel.WorkloadIdentityTargetTypeServiceAccount, + ServiceAccountID: *in.ServiceAccountID, + } + changed = true + } + authorization, set, err := buildWorkloadIdentityAuthorization(in.Authorization) + if err != nil { + return err + } + if set { + params.Authorization = authorization + changed = true + } + if !changed { + return fmt.Errorf("nothing to update: pass at least one mutable field") + } + + rule, err := c.rules.Update(ctx, in.ID, params) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(rule) + } + pterm.Success.Printf("Updated workload identity federation rule: %s\n", rule.ID) + printWorkloadIdentityFederationRuleDetail(rule) + return nil +} + +func (c WorkloadIdentityFederationRulesCmd) Delete(ctx context.Context, in WorkloadIdentityFederationRuleDeleteInput) error { + if !in.SkipConfirm { + ok, err := c.prompter.Confirm( + fmt.Sprintf("archive workload identity federation rule '%s'", in.ID), + fmt.Sprintf("Archive workload identity federation rule '%s'? Authentication history is retained, but the rule can no longer issue credentials.", in.ID), + ) + if err != nil { + return err + } + if !ok { + pterm.Info.Println("Archive cancelled") + return nil + } + } + if err := c.rules.Delete(ctx, in.ID); err != nil { + return util.CleanedUpSdkError{Err: err} + } + pterm.Success.Printf("Archived workload identity federation rule: %s\n", in.ID) + return nil +} + +func buildWorkloadIdentityMatch(in WorkloadIdentityMatchInput) (kernel.WorkloadIdentityMatchParam, bool, error) { + if !in.Set { + return kernel.WorkloadIdentityMatchParam{}, false, nil + } + matchType, err := parseWorkloadIdentityMatchType(in.Type) + if err != nil { + return kernel.WorkloadIdentityMatchParam{}, false, err + } + result := kernel.WorkloadIdentityMatchParam{Type: matchType} + if in.Subject != nil { + if err := validateOptionalMatchString("--match-subject", *in.Subject, 1024, true); err != nil { + return result, false, err + } + result.Subject = kernel.Opt(*in.Subject) + } + if in.SubjectPrefix != nil { + if err := validateOptionalMatchString("--match-subject-prefix", *in.SubjectPrefix, 1024, true); err != nil { + return result, false, err + } + result.SubjectPrefix = kernel.Opt(*in.SubjectPrefix) + } + if in.ClaimsSet { + if len(in.Claims) > 32 { + return result, false, fmt.Errorf("--match-claim may be repeated at most 32 times") + } + for pointer, value := range in.Claims { + if len(value) < 1 || len(value) > 1024 { + return result, false, fmt.Errorf("--match-claim value for %q must contain 1-1024 characters", pointer) + } + } + result.Claims = in.Claims + } + if in.Repository != nil { + if err := validateOptionalMatchString("--match-repository", *in.Repository, 256, false); err != nil { + return result, false, err + } + result.Repository = kernel.Opt(*in.Repository) + } + if in.RepositoryID != nil { + if err := validateNumericMatchID("--match-repository-id", *in.RepositoryID); err != nil { + return result, false, err + } + result.RepositoryID = kernel.Opt(*in.RepositoryID) + } + if in.RepositoryOwnerID != nil { + if err := validateNumericMatchID("--match-repository-owner-id", *in.RepositoryOwnerID); err != nil { + return result, false, err + } + result.RepositoryOwnerID = kernel.Opt(*in.RepositoryOwnerID) + } + if in.Workflow != nil { + if err := validateOptionalMatchString("--match-workflow", *in.Workflow, 512, false); err != nil { + return result, false, err + } + result.Workflow = kernel.Opt(*in.Workflow) + } + if in.WorkflowRef != nil { + if err := validateOptionalMatchString("--match-workflow-ref", *in.WorkflowRef, 1024, false); err != nil { + return result, false, err + } + result.WorkflowRef = kernel.Opt(*in.WorkflowRef) + } + if in.JobWorkflowRef != nil { + if err := validateOptionalMatchString("--match-job-workflow-ref", *in.JobWorkflowRef, 1024, false); err != nil { + return result, false, err + } + result.JobWorkflowRef = kernel.Opt(*in.JobWorkflowRef) + } + if in.Ref != nil { + if err := validateOptionalMatchString("--match-ref", *in.Ref, 512, false); err != nil { + return result, false, err + } + result.Ref = kernel.Opt(*in.Ref) + } + if in.Environment != nil { + if err := validateOptionalMatchString("--match-environment", *in.Environment, 256, false); err != nil { + return result, false, err + } + result.Environment = kernel.Opt(*in.Environment) + } + if in.EventNamesSet { + if len(in.EventNames) < 1 || len(in.EventNames) > 20 { + return result, false, fmt.Errorf("--match-event-name must be repeated between 1 and 20 times") + } + for _, eventName := range in.EventNames { + if len(eventName) < 1 || len(eventName) > 128 { + return result, false, fmt.Errorf("each --match-event-name must contain 1-128 characters") + } + } + result.EventNames = in.EventNames + } + if in.Namespace != nil { + if err := validateOptionalMatchString("--match-namespace", *in.Namespace, 63, false); err != nil { + return result, false, err + } + result.Namespace = kernel.Opt(*in.Namespace) + } + if in.ServiceAccount != nil { + if err := validateOptionalMatchString("--match-service-account", *in.ServiceAccount, 253, false); err != nil { + return result, false, err + } + result.ServiceAccount = kernel.Opt(*in.ServiceAccount) + } + return result, true, nil +} + +func buildWorkloadIdentityAuthorization(in WorkloadIdentityAuthorizationInput) (kernel.WorkloadIdentityAuthorizationParam, bool, error) { + if !in.Set { + return kernel.WorkloadIdentityAuthorizationParam{}, false, nil + } + if err := validateRequiredBoundedString("--project-id", in.ProjectID, 128); err != nil { + return kernel.WorkloadIdentityAuthorizationParam{}, false, fmt.Errorf("authorization replacement requires --project-id: %w", err) + } + if !in.PolicySet { + return kernel.WorkloadIdentityAuthorizationParam{}, false, fmt.Errorf("authorization replacement requires --policy") + } + if err := validateRequiredBoundedString("--token-audience", in.TokenAudience, 2048); err != nil { + return kernel.WorkloadIdentityAuthorizationParam{}, false, fmt.Errorf("authorization replacement requires --token-audience: %w", err) + } + policy, err := parseAPIKeyPolicy[kernel.WorkloadIdentityAuthorizationPolicyParam](in.Policy) + if err != nil { + return kernel.WorkloadIdentityAuthorizationParam{}, false, err + } + result := kernel.WorkloadIdentityAuthorizationParam{ + ProjectID: in.ProjectID, + Policy: policy, + TokenAudience: in.TokenAudience, + } + if in.MaxTokenTTLSeconds.Set { + if in.MaxTokenTTLSeconds.Value < 1 || in.MaxTokenTTLSeconds.Value > 600 { + return result, false, fmt.Errorf("--max-token-ttl-seconds must be between 1 and 600") + } + result.MaxTokenTtlSeconds = kernel.Opt(in.MaxTokenTTLSeconds.Value) + } + return result, true, nil +} + +func validateRequiredBoundedString(flagName, value string, maxLength int) error { + if strings.TrimSpace(value) == "" { + return fmt.Errorf("%s is required", flagName) + } + if len(value) > maxLength { + return fmt.Errorf("%s must be at most %d characters", flagName, maxLength) + } + return nil +} + +func parseWorkloadIdentityMatchType(value string) (kernel.WorkloadIdentityMatchType, error) { + switch value { + case string(kernel.WorkloadIdentityMatchTypeGitHubActions): + return kernel.WorkloadIdentityMatchTypeGitHubActions, nil + case string(kernel.WorkloadIdentityMatchTypeAws): + return kernel.WorkloadIdentityMatchTypeAws, nil + case string(kernel.WorkloadIdentityMatchTypeGoogleCloud): + return kernel.WorkloadIdentityMatchTypeGoogleCloud, nil + case string(kernel.WorkloadIdentityMatchTypeMicrosoftEntra): + return kernel.WorkloadIdentityMatchTypeMicrosoftEntra, nil + case string(kernel.WorkloadIdentityMatchTypeKubernetes): + return kernel.WorkloadIdentityMatchTypeKubernetes, nil + case string(kernel.WorkloadIdentityMatchTypeCustomOidc): + return kernel.WorkloadIdentityMatchTypeCustomOidc, nil + case "": + return "", fmt.Errorf("--match-type is required when setting match fields") + default: + return "", fmt.Errorf("invalid --match-type %q: must be one of github_actions, aws, google_cloud, microsoft_entra, kubernetes, custom_oidc", value) + } +} + +func validateOptionalMatchString(flagName, value string, maxLength int, requireNonEmpty bool) error { + if requireNonEmpty && value == "" { + return fmt.Errorf("%s must not be empty", flagName) + } + if len(value) > maxLength { + return fmt.Errorf("%s must be at most %d characters", flagName, maxLength) + } + return nil +} + +var numericWorkloadIdentityID = regexp.MustCompile(`^[0-9]+$`) + +func validateNumericMatchID(flagName, value string) error { + if len(value) > 32 || !numericWorkloadIdentityID.MatchString(value) { + return fmt.Errorf("%s must contain 1-32 decimal digits", flagName) + } + return nil +} + +func printWorkloadIdentityFederationRuleDetail(rule *kernel.WorkloadIdentityFederationRule) { + if rule == nil { + pterm.Info.Println("Workload identity federation rule not found") + return + } + rows := pterm.TableData{ + {"Property", "Value"}, + {"ID", rule.ID}, + {"Name", rule.Name}, + {"Description", util.OrDash(rule.Description)}, + {"Status", workloadIdentityResourceStatus(rule.JSON.ArchivedAt.Valid())}, + {"Enabled", fmt.Sprintf("%t", rule.Enabled)}, + {"Issuer ID", rule.IssuerID}, + {"Expected Audience", rule.ExpectedAudience}, + {"Match Type", string(rule.Match.Type)}, + {"Match Subject", util.OrDash(rule.Match.Subject)}, + {"Match Subject Prefix", util.OrDash(rule.Match.SubjectPrefix)}, + {"Match Claims", formatStringMap(rule.Match.Claims)}, + {"Match Repository", util.OrDash(rule.Match.Repository)}, + {"Match Repository ID", util.OrDash(rule.Match.RepositoryID)}, + {"Match Repository Owner ID", util.OrDash(rule.Match.RepositoryOwnerID)}, + {"Match Workflow", util.OrDash(rule.Match.Workflow)}, + {"Match Workflow Ref", util.OrDash(rule.Match.WorkflowRef)}, + {"Match Job Workflow Ref", util.OrDash(rule.Match.JobWorkflowRef)}, + {"Match Ref", util.OrDash(rule.Match.Ref)}, + {"Match Environment", util.OrDash(rule.Match.Environment)}, + {"Match Event Names", util.OrDash(strings.Join(rule.Match.EventNames, ", "))}, + {"Match Namespace", util.OrDash(rule.Match.Namespace)}, + {"Match Service Account", util.OrDash(rule.Match.ServiceAccount)}, + {"Target Type", string(rule.Target.Type)}, + {"Target Service Account ID", rule.Target.ServiceAccountID}, + {"Authorization Project ID", rule.Authorization.ProjectID}, + {"Authorization Token Audience", rule.Authorization.TokenAudience}, + {"Authorization Max Token TTL Seconds", formatOptionalPositiveInt(rule.Authorization.MaxTokenTtlSeconds)}, + {"Authorization Policy Statements", fmt.Sprintf("%d", len(rule.Authorization.Policy.Statements))}, + {"Security Version", fmt.Sprintf("%d", rule.SecurityVersion)}, + {"Created By User ID", util.OrDash(rule.CreatedByUserID)}, + {"Last Exchange At", util.FormatLocal(rule.LastExchangeAt)}, + {"Archived At", util.FormatLocal(rule.ArchivedAt)}, + {"Created At", util.FormatLocal(rule.CreatedAt)}, + {"Updated At", util.FormatLocal(rule.UpdatedAt)}, + } + PrintTableNoPad(rows, true) +} + +var workloadIdentityFederationRulesCmd = &cobra.Command{ + Use: "federation-rules", + Aliases: []string{"federation-rule", "rules", "rule"}, + Short: "Manage workload identity federation rules", + Long: "Manage rules that map trusted issuer claims to a service account and a project-scoped authorization policy. " + + "Reading requires a signed-in organization member; mutations require credential administrator access.", + Run: func(cmd *cobra.Command, args []string) { _ = cmd.Help() }, +} + +var workloadIdentityFederationRulesListCmd = &cobra.Command{ + Use: "list", + Short: "List workload identity federation rule records", + Long: "List federation rules. Search matches name or description case-insensitively and matches an exact rule ID. " + + "Any signed-in organization member can read this; Kernel API keys cannot.", + Args: cobra.NoArgs, + RunE: runWorkloadIdentityFederationRulesList, +} + +var workloadIdentityFederationRulesGetCmd = &cobra.Command{ + Use: "get ", + Short: "Get a workload identity federation rule", + Long: "Get a federation rule by its stable resource ID. Any signed-in organization member can read this; Kernel API keys cannot.", + Args: cobra.ExactArgs(1), + RunE: runWorkloadIdentityFederationRulesGet, +} + +var workloadIdentityFederationRulesCreateCmd = &cobra.Command{ + Use: "create --name --issuer-id --match-type --expected-audience --service-account-id --project-id --policy --token-audience ", + Short: "Create a workload identity federation rule", + Long: "Create a disabled-by-default rule that maps incoming issuer claims to a service account. Organization credential administrator access is required; " + + "no external namespace-ownership or staff approval is required. All configured match conditions are ANDed. The policy uses scoped API-key policy syntax, " + + "but API-key administration actions are not allowed. Every action and resource not listed is denied.", + Args: cobra.NoArgs, + RunE: runWorkloadIdentityFederationRulesCreate, +} + +var workloadIdentityFederationRulesUpdateCmd = &cobra.Command{ + Use: "update --expected-version ", + Short: "Update a workload identity federation rule", + Long: "Update a rule using optimistic concurrency. Match and authorization are replaced as whole objects: when changing any match field, pass --match-type and every match condition to retain; " + + "when changing authorization, pass --project-id, --policy, and --token-audience together.", + Args: cobra.ExactArgs(1), + RunE: runWorkloadIdentityFederationRulesUpdate, +} + +var workloadIdentityFederationRulesDeleteCmd = &cobra.Command{ + Use: "delete ", + Aliases: []string{"archive"}, + Short: "Archive a workload identity federation rule", + Long: "Archive a federation rule. This retains history and invalidates associated authority within the documented status bound; it does not delete browser resources created through the rule.", + Args: cobra.ExactArgs(1), + RunE: runWorkloadIdentityFederationRulesDelete, +} + +func addWorkloadIdentityFederationRuleMutationFlags(cmd *cobra.Command, update bool) { + addJSONOutputFlag(cmd) + cmd.Flags().String("name", "", "Rule name; starts with a letter or number and contains only letters, numbers, and hyphens") + cmd.Flags().String("description", "", "Description (maximum 4096 characters); on update, pass an empty string to clear it") + cmd.Flags().String("issuer-id", "", "Trusted workload identity issuer ID") + cmd.Flags().String("expected-audience", "", "Exact audience required in the incoming token (maximum 2048 characters)") + cmd.Flags().Bool("enabled", false, "Whether this rule may issue credentials") + cmd.Flags().String("match-type", "", "Issuer preset type: github_actions, aws, google_cloud, microsoft_entra, kubernetes, or custom_oidc") + cmd.Flags().String("match-subject", "", "Exact incoming subject (1-1024 characters)") + cmd.Flags().String("match-subject-prefix", "", "Required incoming subject prefix (1-1024 characters)") + cmd.Flags().StringArray("match-claim", nil, "Exact RFC 6901 JSON Pointer claim condition as POINTER=VALUE; all conditions are ANDed (repeatable, maximum 32)") + cmd.Flags().String("match-repository", "", "GitHub repository display name (maximum 256 characters); immutable IDs define identity") + cmd.Flags().String("match-repository-id", "", "GitHub repository ID (1-32 decimal digits)") + cmd.Flags().String("match-repository-owner-id", "", "GitHub repository owner ID (1-32 decimal digits)") + cmd.Flags().String("match-workflow", "", "GitHub workflow name (maximum 512 characters)") + cmd.Flags().String("match-workflow-ref", "", "GitHub workflow reference (maximum 1024 characters)") + cmd.Flags().String("match-job-workflow-ref", "", "GitHub reusable job workflow reference (maximum 1024 characters)") + cmd.Flags().String("match-ref", "", "Git reference (maximum 512 characters)") + cmd.Flags().String("match-environment", "", "GitHub environment (maximum 256 characters)") + cmd.Flags().StringArray("match-event-name", nil, "Allowed GitHub event name (repeatable, 1-20 values of at most 128 characters)") + cmd.Flags().String("match-namespace", "", "Kubernetes namespace (maximum 63 characters)") + cmd.Flags().String("match-service-account", "", "Kubernetes service account name (maximum 253 characters)") + cmd.Flags().String("service-account-id", "", "Target Kernel service account ID") + cmd.Flags().String("project-id", "", "One project to which issued credentials are limited") + cmd.Flags().String("policy", "", "JSON allow policy in scoped API-key format; API-key administration actions are not allowed") + cmd.Flags().String("token-audience", "", "Audience placed in the issued credential (maximum 2048 characters)") + cmd.Flags().Int64("max-token-ttl-seconds", 0, "Maximum issued credential lifetime, from 1 to 600 seconds (default 300)") + if update { + cmd.Flags().Int64("expected-version", 0, "Current security_version used for optimistic concurrency (required)") + _ = cmd.MarkFlagRequired("expected-version") + } else { + for _, flag := range []string{"name", "issuer-id", "expected-audience", "match-type", "service-account-id", "project-id", "policy", "token-audience"} { + _ = cmd.MarkFlagRequired(flag) + } + } +} + +func init() { + addJSONOutputFlag(workloadIdentityFederationRulesListCmd) + workloadIdentityFederationRulesListCmd.Flags().Int("page", 1, "Page number (1-based)") + workloadIdentityFederationRulesListCmd.Flags().Int("per-page", 20, "Items per page (1-99; default 20)") + workloadIdentityFederationRulesListCmd.Flags().String("issuer-id", "", "Filter by exact issuer ID") + workloadIdentityFederationRulesListCmd.Flags().String("project-id", "", "Filter by exact authorization project ID") + workloadIdentityFederationRulesListCmd.Flags().String("query", "", "Case-insensitive search by name or description; an exact rule ID also matches (maximum 256 characters)") + workloadIdentityFederationRulesListCmd.Flags().String("service-account-id", "", "Filter by exact target service account ID") + workloadIdentityFederationRulesListCmd.Flags().String("status", "", "Filter by lifecycle status: active, archived, or all") + + addJSONOutputFlag(workloadIdentityFederationRulesGetCmd) + addWorkloadIdentityFederationRuleMutationFlags(workloadIdentityFederationRulesCreateCmd, false) + addWorkloadIdentityFederationRuleMutationFlags(workloadIdentityFederationRulesUpdateCmd, true) + workloadIdentityFederationRulesDeleteCmd.Flags().BoolP("yes", "y", false, "Skip confirmation prompt") + + workloadIdentityFederationRulesCmd.AddCommand( + workloadIdentityFederationRulesListCmd, + workloadIdentityFederationRulesGetCmd, + workloadIdentityFederationRulesCreateCmd, + workloadIdentityFederationRulesUpdateCmd, + workloadIdentityFederationRulesDeleteCmd, + ) + workloadIdentityCmd.AddCommand(workloadIdentityFederationRulesCmd) +} + +func getWorkloadIdentityFederationRulesHandler(cmd *cobra.Command) WorkloadIdentityFederationRulesCmd { + client := getKernelClient(cmd) + return WorkloadIdentityFederationRulesCmd{rules: &client.WorkloadIdentityFederationRules, prompter: interactive.NewPrompter()} +} + +func workloadIdentityMatchInputFromFlags(cmd *cobra.Command) (WorkloadIdentityMatchInput, error) { + result := WorkloadIdentityMatchInput{} + result.Type, _ = cmd.Flags().GetString("match-type") + for flag, target := range map[string]**string{ + "match-subject": &result.Subject, + "match-subject-prefix": &result.SubjectPrefix, + "match-repository": &result.Repository, + "match-repository-id": &result.RepositoryID, + "match-repository-owner-id": &result.RepositoryOwnerID, + "match-workflow": &result.Workflow, + "match-workflow-ref": &result.WorkflowRef, + "match-job-workflow-ref": &result.JobWorkflowRef, + "match-ref": &result.Ref, + "match-environment": &result.Environment, + "match-namespace": &result.Namespace, + "match-service-account": &result.ServiceAccount, + } { + if cmd.Flags().Changed(flag) { + value, _ := cmd.Flags().GetString(flag) + valueCopy := value + *target = &valueCopy + } + } + claimSpecs, _ := cmd.Flags().GetStringArray("match-claim") + if cmd.Flags().Changed("match-claim") { + claims, err := parseStringMapFlag(claimSpecs, "--match-claim") + if err != nil { + return result, err + } + result.Claims = claims + result.ClaimsSet = true + } + result.EventNames, _ = cmd.Flags().GetStringArray("match-event-name") + result.EventNamesSet = cmd.Flags().Changed("match-event-name") + result.Set = cmd.Flags().Changed("match-type") || result.Subject != nil || result.SubjectPrefix != nil || result.ClaimsSet || + result.Repository != nil || result.RepositoryID != nil || result.RepositoryOwnerID != nil || result.Workflow != nil || + result.WorkflowRef != nil || result.JobWorkflowRef != nil || result.Ref != nil || result.Environment != nil || + result.EventNamesSet || result.Namespace != nil || result.ServiceAccount != nil + return result, nil +} + +func workloadIdentityAuthorizationInputFromFlags(cmd *cobra.Command) WorkloadIdentityAuthorizationInput { + projectID, _ := cmd.Flags().GetString("project-id") + policy, _ := cmd.Flags().GetString("policy") + tokenAudience, _ := cmd.Flags().GetString("token-audience") + maxTTL, _ := cmd.Flags().GetInt64("max-token-ttl-seconds") + result := WorkloadIdentityAuthorizationInput{ + ProjectID: projectID, Policy: policy, PolicySet: cmd.Flags().Changed("policy"), TokenAudience: tokenAudience, + MaxTokenTTLSeconds: Int64Flag{Set: cmd.Flags().Changed("max-token-ttl-seconds"), Value: maxTTL}, + } + result.Set = cmd.Flags().Changed("project-id") || result.PolicySet || cmd.Flags().Changed("token-audience") || result.MaxTokenTTLSeconds.Set + return result +} + +func runWorkloadIdentityFederationRulesList(cmd *cobra.Command, args []string) error { + page, _ := cmd.Flags().GetInt("page") + perPage, _ := cmd.Flags().GetInt("per-page") + issuerID, _ := cmd.Flags().GetString("issuer-id") + projectID, _ := cmd.Flags().GetString("project-id") + query, _ := cmd.Flags().GetString("query") + serviceAccountID, _ := cmd.Flags().GetString("service-account-id") + status, _ := cmd.Flags().GetString("status") + output, _ := cmd.Flags().GetString("output") + return getWorkloadIdentityFederationRulesHandler(cmd).List(cmd.Context(), WorkloadIdentityFederationRulesListInput{ + Page: page, PerPage: perPage, IssuerID: issuerID, ProjectID: projectID, Query: query, ServiceAccountID: serviceAccountID, Status: status, Output: output, + }) +} + +func runWorkloadIdentityFederationRulesGet(cmd *cobra.Command, args []string) error { + output, _ := cmd.Flags().GetString("output") + return getWorkloadIdentityFederationRulesHandler(cmd).Get(cmd.Context(), WorkloadIdentityFederationRuleGetInput{ID: args[0], Output: output}) +} + +func runWorkloadIdentityFederationRulesCreate(cmd *cobra.Command, args []string) error { + match, err := workloadIdentityMatchInputFromFlags(cmd) + if err != nil { + return err + } + name, _ := cmd.Flags().GetString("name") + description, _ := cmd.Flags().GetString("description") + issuerID, _ := cmd.Flags().GetString("issuer-id") + expectedAudience, _ := cmd.Flags().GetString("expected-audience") + serviceAccountID, _ := cmd.Flags().GetString("service-account-id") + output, _ := cmd.Flags().GetString("output") + return getWorkloadIdentityFederationRulesHandler(cmd).Create(cmd.Context(), WorkloadIdentityFederationRuleCreateInput{ + Name: name, Description: description, IssuerID: issuerID, ExpectedAudience: expectedAudience, + Enabled: readBoolFlag(cmd.Flags(), "enabled"), Match: match, ServiceAccountID: serviceAccountID, + Authorization: workloadIdentityAuthorizationInputFromFlags(cmd), Output: output, + }) +} + +func runWorkloadIdentityFederationRulesUpdate(cmd *cobra.Command, args []string) error { + match, err := workloadIdentityMatchInputFromFlags(cmd) + if err != nil { + return err + } + expectedVersion, _ := cmd.Flags().GetInt64("expected-version") + name, _ := cmd.Flags().GetString("name") + description, _ := cmd.Flags().GetString("description") + issuerID, _ := cmd.Flags().GetString("issuer-id") + expectedAudience, _ := cmd.Flags().GetString("expected-audience") + serviceAccountID, _ := cmd.Flags().GetString("service-account-id") + output, _ := cmd.Flags().GetString("output") + var namePtr, descriptionPtr, issuerIDPtr, expectedAudiencePtr, serviceAccountIDPtr *string + if cmd.Flags().Changed("name") { + namePtr = &name + } + if cmd.Flags().Changed("description") { + descriptionPtr = &description + } + if cmd.Flags().Changed("issuer-id") { + issuerIDPtr = &issuerID + } + if cmd.Flags().Changed("expected-audience") { + expectedAudiencePtr = &expectedAudience + } + if cmd.Flags().Changed("service-account-id") { + serviceAccountIDPtr = &serviceAccountID + } + return getWorkloadIdentityFederationRulesHandler(cmd).Update(cmd.Context(), WorkloadIdentityFederationRuleUpdateInput{ + ID: args[0], ExpectedVersion: expectedVersion, Name: namePtr, Description: descriptionPtr, IssuerID: issuerIDPtr, + ExpectedAudience: expectedAudiencePtr, Enabled: readBoolFlag(cmd.Flags(), "enabled"), Match: match, + ServiceAccountID: serviceAccountIDPtr, Authorization: workloadIdentityAuthorizationInputFromFlags(cmd), Output: output, + }) +} + +func runWorkloadIdentityFederationRulesDelete(cmd *cobra.Command, args []string) error { + yes, _ := cmd.Flags().GetBool("yes") + return getWorkloadIdentityFederationRulesHandler(cmd).Delete(cmd.Context(), WorkloadIdentityFederationRuleDeleteInput{ID: args[0], SkipConfirm: yes}) +} diff --git a/cmd/workload_identity_issuers.go b/cmd/workload_identity_issuers.go new file mode 100644 index 00000000..c7b958e7 --- /dev/null +++ b/cmd/workload_identity_issuers.go @@ -0,0 +1,726 @@ +package cmd + +import ( + "context" + "encoding/json" + "fmt" + "sort" + + "github.com/kernel/cli/pkg/interactive" + "github.com/kernel/cli/pkg/util" + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + "github.com/kernel/kernel-go-sdk/packages/pagination" + "github.com/pterm/pterm" + "github.com/spf13/cobra" +) + +// WorkloadIdentityIssuersService is the subset of the SDK service used by the CLI. +type WorkloadIdentityIssuersService interface { + New(ctx context.Context, body kernel.WorkloadIdentityIssuerNewParams, opts ...option.RequestOption) (*kernel.WorkloadIdentityIssuer, error) + Get(ctx context.Context, id string, opts ...option.RequestOption) (*kernel.WorkloadIdentityIssuer, error) + Update(ctx context.Context, id string, body kernel.WorkloadIdentityIssuerUpdateParams, opts ...option.RequestOption) (*kernel.WorkloadIdentityIssuer, error) + List(ctx context.Context, query kernel.WorkloadIdentityIssuerListParams, opts ...option.RequestOption) (*pagination.OffsetPagination[kernel.WorkloadIdentityIssuer], error) + Delete(ctx context.Context, id string, opts ...option.RequestOption) error + Verify(ctx context.Context, id string, opts ...option.RequestOption) (*kernel.WorkloadIdentityIssuerKeyCheck, error) +} + +type WorkloadIdentityIssuersCmd struct { + issuers WorkloadIdentityIssuersService + prompter interactive.Prompter +} + +type WorkloadIdentityIssuersListInput struct { + Page int + PerPage int + Query string + Status string + Enabled BoolFlag + Output string +} + +type WorkloadIdentityIssuerGetInput struct { + ID string + Output string +} + +type WorkloadIdentityKeySourceInput struct { + Set bool + Type string + URL *string + DiscoveryBaseURL *string + CACertPEM *string + KeysJSON *string +} + +type WorkloadIdentityTokenValidationInput struct { + Set bool + MaxLifetimeSeconds Int64Flag + ReplayProtection *string +} + +type WorkloadIdentityIssuerCreateInput struct { + Name string + Description string + IssuerURL *string + PresetType *string + Enabled BoolFlag + JWKS WorkloadIdentityKeySourceInput + TokenValidation WorkloadIdentityTokenValidationInput + Output string +} + +type WorkloadIdentityIssuerUpdateInput struct { + ID string + ExpectedVersion int64 + Name *string + Description *string + IssuerURL *string + PresetType *string + Enabled BoolFlag + JWKS WorkloadIdentityKeySourceInput + TokenValidation WorkloadIdentityTokenValidationInput + Output string +} + +type WorkloadIdentityIssuerDeleteInput struct { + ID string + SkipConfirm bool +} + +type WorkloadIdentityIssuerVerifyInput struct { + ID string + Output string +} + +func (c WorkloadIdentityIssuersCmd) List(ctx context.Context, in WorkloadIdentityIssuersListInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + page, perPage, err := normalizePageInput(in.Page, in.PerPage) + if err != nil { + return err + } + status, err := validateWorkloadIdentityListStatus(in.Status) + if err != nil { + return err + } + if len(in.Query) > 256 { + return fmt.Errorf("--query must be at most 256 characters") + } + + params := kernel.WorkloadIdentityIssuerListParams{ + Limit: kernel.Opt(int64(perPage + 1)), + Offset: kernel.Opt(int64((page - 1) * perPage)), + } + if in.Query != "" { + params.Query = kernel.Opt(in.Query) + } + if status != "" { + params.Status = kernel.WorkloadIdentityIssuerListParamsStatus(status) + } + if in.Enabled.Set { + params.Enabled = kernel.Opt(in.Enabled.Value) + } + + result, err := c.issuers.List(ctx, params) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + items := []kernel.WorkloadIdentityIssuer{} + if result != nil { + items = result.Items + } + hasMore := len(items) > perPage + if hasMore { + items = items[:perPage] + } + + if in.Output == "json" { + return util.PrintPageJSON(items, page, perPage, hasMore) + } + if len(items) == 0 { + pterm.Info.Println("No workload identity issuers found") + } else { + rows := pterm.TableData{{"ID", "Name", "Preset", "Issuer URL", "JWKS", "Enabled", "Status", "Security Version"}} + for _, issuer := range items { + rows = append(rows, []string{ + issuer.ID, + issuer.Name, + string(issuer.PresetType), + util.OrDash(issuer.IssuerURL), + string(issuer.Jwks.Type), + fmt.Sprintf("%t", issuer.Enabled), + workloadIdentityResourceStatus(issuer.JSON.ArchivedAt.Valid()), + fmt.Sprintf("%d", issuer.SecurityVersion), + }) + } + PrintTableNoPad(rows, true) + } + + filters := "" + if in.Query != "" { + filters += fmt.Sprintf(" --query %q", in.Query) + } + if status != "" { + filters += fmt.Sprintf(" --status %s", status) + } + if in.Enabled.Set { + filters += fmt.Sprintf(" --enabled=%t", in.Enabled.Value) + } + nextCommand := fmt.Sprintf("kernel workload-identity issuers list --page %d --per-page %d%s", page+1, perPage, filters) + printListPaginationFooter(page, perPage, len(items), hasMore, nextCommand) + return nil +} + +func (c WorkloadIdentityIssuersCmd) Get(ctx context.Context, in WorkloadIdentityIssuerGetInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + issuer, err := c.issuers.Get(ctx, in.ID) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(issuer) + } + printWorkloadIdentityIssuerDetail(issuer) + return nil +} + +func (c WorkloadIdentityIssuersCmd) Create(ctx context.Context, in WorkloadIdentityIssuerCreateInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + name, err := validateWorkloadIdentityName(in.Name, "name") + if err != nil { + return err + } + if err := validateWorkloadIdentityDescription(in.Description); err != nil { + return err + } + + config := kernel.WorkloadIdentityIssuerConfigParam{Name: name} + if in.Description != "" { + config.Description = kernel.Opt(in.Description) + } + if in.IssuerURL != nil { + if len(*in.IssuerURL) > 2048 { + return fmt.Errorf("--issuer-url must be at most 2048 characters") + } + config.IssuerURL = kernel.Opt(*in.IssuerURL) + } + if in.PresetType != nil { + preset, err := parseWorkloadIdentityPresetType(*in.PresetType) + if err != nil { + return err + } + config.PresetType = preset + } + if in.Enabled.Set { + config.Enabled = kernel.Opt(in.Enabled.Value) + } + jwks, set, err := buildWorkloadIdentityKeySource(in.JWKS) + if err != nil { + return err + } + if set { + config.Jwks = jwks + } + validation, set, err := buildWorkloadIdentityTokenValidation(in.TokenValidation) + if err != nil { + return err + } + if set { + config.TokenValidation = validation + } + + issuer, err := c.issuers.New(ctx, kernel.WorkloadIdentityIssuerNewParams{WorkloadIdentityIssuerConfig: config}) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(issuer) + } + pterm.Success.Printf("Created workload identity issuer: %s\n", issuer.ID) + printWorkloadIdentityIssuerDetail(issuer) + return nil +} + +func (c WorkloadIdentityIssuersCmd) Update(ctx context.Context, in WorkloadIdentityIssuerUpdateInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + if in.ExpectedVersion < 1 { + return fmt.Errorf("--expected-version must be at least 1") + } + params := kernel.WorkloadIdentityIssuerUpdateParams{ExpectedVersion: in.ExpectedVersion} + changed := false + if in.Name != nil { + name, err := validateWorkloadIdentityName(*in.Name, "name") + if err != nil { + return err + } + params.Name = kernel.Opt(name) + changed = true + } + if in.Description != nil { + if err := validateWorkloadIdentityDescription(*in.Description); err != nil { + return err + } + params.Description = kernel.Opt(*in.Description) + changed = true + } + if in.IssuerURL != nil { + if len(*in.IssuerURL) > 2048 { + return fmt.Errorf("--issuer-url must be at most 2048 characters") + } + params.IssuerURL = kernel.Opt(*in.IssuerURL) + changed = true + } + if in.PresetType != nil { + preset, err := parseWorkloadIdentityPresetType(*in.PresetType) + if err != nil { + return err + } + params.PresetType = preset + changed = true + } + if in.Enabled.Set { + params.Enabled = kernel.Opt(in.Enabled.Value) + changed = true + } + jwks, set, err := buildWorkloadIdentityKeySource(in.JWKS) + if err != nil { + return err + } + if set { + params.Jwks = jwks + changed = true + } + validation, set, err := buildWorkloadIdentityTokenValidation(in.TokenValidation) + if err != nil { + return err + } + if set { + params.TokenValidation = validation + changed = true + } + if !changed { + return fmt.Errorf("nothing to update: pass at least one mutable field") + } + + issuer, err := c.issuers.Update(ctx, in.ID, params) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(issuer) + } + pterm.Success.Printf("Updated workload identity issuer: %s\n", issuer.ID) + printWorkloadIdentityIssuerDetail(issuer) + return nil +} + +func (c WorkloadIdentityIssuersCmd) Delete(ctx context.Context, in WorkloadIdentityIssuerDeleteInput) error { + if !in.SkipConfirm { + ok, err := c.prompter.Confirm( + fmt.Sprintf("archive workload identity issuer '%s'", in.ID), + fmt.Sprintf("Archive workload identity issuer '%s'? Its rules and authentication history are retained, but it can no longer issue credentials.", in.ID), + ) + if err != nil { + return err + } + if !ok { + pterm.Info.Println("Archive cancelled") + return nil + } + } + if err := c.issuers.Delete(ctx, in.ID); err != nil { + return util.CleanedUpSdkError{Err: err} + } + pterm.Success.Printf("Archived workload identity issuer: %s\n", in.ID) + return nil +} + +func (c WorkloadIdentityIssuersCmd) Verify(ctx context.Context, in WorkloadIdentityIssuerVerifyInput) error { + if err := validateJSONOutput(in.Output); err != nil { + return err + } + result, err := c.issuers.Verify(ctx, in.ID) + if err != nil { + return util.CleanedUpSdkError{Err: err} + } + if in.Output == "json" { + return util.PrintPrettyJSON(result) + } + pterm.Success.Printf("Verified issuer keys for %s\n", result.IssuerID) + if len(result.KeyIDs) == 0 { + pterm.Info.Println("No key IDs were returned") + return nil + } + keyIDs := append([]string(nil), result.KeyIDs...) + sort.Strings(keyIDs) + rows := pterm.TableData{{"Key ID"}} + for _, keyID := range keyIDs { + rows = append(rows, []string{keyID}) + } + PrintTableNoPad(rows, true) + return nil +} + +func buildWorkloadIdentityKeySource(in WorkloadIdentityKeySourceInput) (kernel.WorkloadIdentityKeySourceParam, bool, error) { + if !in.Set { + return kernel.WorkloadIdentityKeySourceParam{}, false, nil + } + var keyType kernel.WorkloadIdentityKeySourceType + switch in.Type { + case string(kernel.WorkloadIdentityKeySourceTypeDiscovery): + keyType = kernel.WorkloadIdentityKeySourceTypeDiscovery + case string(kernel.WorkloadIdentityKeySourceTypeExplicitURL): + keyType = kernel.WorkloadIdentityKeySourceTypeExplicitURL + case string(kernel.WorkloadIdentityKeySourceTypeInline): + keyType = kernel.WorkloadIdentityKeySourceTypeInline + case "": + return kernel.WorkloadIdentityKeySourceParam{}, false, fmt.Errorf("--jwks-type is required when setting JWKS fields") + default: + return kernel.WorkloadIdentityKeySourceParam{}, false, fmt.Errorf("invalid --jwks-type %q: must be one of discovery, explicit_url, inline", in.Type) + } + result := kernel.WorkloadIdentityKeySourceParam{Type: keyType} + if in.URL != nil { + if len(*in.URL) > 2048 { + return result, false, fmt.Errorf("--jwks-url must be at most 2048 characters") + } + result.URL = kernel.Opt(*in.URL) + } + if in.DiscoveryBaseURL != nil { + if len(*in.DiscoveryBaseURL) > 2048 { + return result, false, fmt.Errorf("--jwks-discovery-base-url must be at most 2048 characters") + } + result.DiscoveryBaseURL = kernel.Opt(*in.DiscoveryBaseURL) + } + if in.CACertPEM != nil { + if len(*in.CACertPEM) > 65536 { + return result, false, fmt.Errorf("--jwks-ca-cert-pem must be at most 65536 characters") + } + result.CaCertPem = kernel.Opt(*in.CACertPEM) + } + if in.KeysJSON != nil { + var keys []map[string]any + if err := json.Unmarshal([]byte(*in.KeysJSON), &keys); err != nil { + return result, false, fmt.Errorf("invalid --jwks-keys JSON: expected an array of JWK objects: %w", err) + } + if len(keys) < 1 || len(keys) > 16 { + return result, false, fmt.Errorf("--jwks-keys must contain between 1 and 16 JWK objects") + } + for i, key := range keys { + if key == nil { + return result, false, fmt.Errorf("--jwks-keys entry %d must be a JSON object, not null", i) + } + } + result.Keys = keys + } + return result, true, nil +} + +func buildWorkloadIdentityTokenValidation(in WorkloadIdentityTokenValidationInput) (kernel.WorkloadIdentityTokenValidationParam, bool, error) { + if !in.Set { + return kernel.WorkloadIdentityTokenValidationParam{}, false, nil + } + result := kernel.WorkloadIdentityTokenValidationParam{} + if in.MaxLifetimeSeconds.Set { + if in.MaxLifetimeSeconds.Value < 1 || in.MaxLifetimeSeconds.Value > 86400 { + return result, false, fmt.Errorf("--token-max-lifetime-seconds must be between 1 and 86400") + } + result.MaxLifetimeSeconds = kernel.Opt(in.MaxLifetimeSeconds.Value) + } + if in.ReplayProtection != nil { + switch *in.ReplayProtection { + case string(kernel.WorkloadIdentityTokenValidationReplayProtectionSingleUse): + result.ReplayProtection = kernel.WorkloadIdentityTokenValidationReplayProtectionSingleUse + case string(kernel.WorkloadIdentityTokenValidationReplayProtectionAllowReuse): + result.ReplayProtection = kernel.WorkloadIdentityTokenValidationReplayProtectionAllowReuse + default: + return result, false, fmt.Errorf("invalid --token-replay-protection %q: must be one of single_use, allow_reuse", *in.ReplayProtection) + } + } + return result, true, nil +} + +func parseWorkloadIdentityPresetType(value string) (kernel.WorkloadIdentityPresetType, error) { + switch value { + case string(kernel.WorkloadIdentityPresetTypeGitHubActions): + return kernel.WorkloadIdentityPresetTypeGitHubActions, nil + case string(kernel.WorkloadIdentityPresetTypeAws): + return kernel.WorkloadIdentityPresetTypeAws, nil + case string(kernel.WorkloadIdentityPresetTypeGoogleCloud): + return kernel.WorkloadIdentityPresetTypeGoogleCloud, nil + case string(kernel.WorkloadIdentityPresetTypeMicrosoftEntra): + return kernel.WorkloadIdentityPresetTypeMicrosoftEntra, nil + case string(kernel.WorkloadIdentityPresetTypeKubernetes): + return kernel.WorkloadIdentityPresetTypeKubernetes, nil + case string(kernel.WorkloadIdentityPresetTypeCustomOidc): + return kernel.WorkloadIdentityPresetTypeCustomOidc, nil + default: + return "", fmt.Errorf("invalid --preset-type %q: must be one of github_actions, aws, google_cloud, microsoft_entra, kubernetes, custom_oidc", value) + } +} + +func printWorkloadIdentityIssuerDetail(issuer *kernel.WorkloadIdentityIssuer) { + if issuer == nil { + pterm.Info.Println("Workload identity issuer not found") + return + } + rows := pterm.TableData{ + {"Property", "Value"}, + {"ID", issuer.ID}, + {"Name", issuer.Name}, + {"Description", util.OrDash(issuer.Description)}, + {"Status", workloadIdentityResourceStatus(issuer.JSON.ArchivedAt.Valid())}, + {"Enabled", fmt.Sprintf("%t", issuer.Enabled)}, + {"Preset Type", string(issuer.PresetType)}, + {"Issuer URL", util.OrDash(issuer.IssuerURL)}, + {"JWKS Type", string(issuer.Jwks.Type)}, + {"JWKS URL", util.OrDash(issuer.Jwks.URL)}, + {"JWKS Discovery Base URL", util.OrDash(issuer.Jwks.DiscoveryBaseURL)}, + {"Inline JWK Count", fmt.Sprintf("%d", len(issuer.Jwks.Keys))}, + {"Token Max Lifetime Seconds", formatOptionalPositiveInt(issuer.TokenValidation.MaxLifetimeSeconds)}, + {"Token Replay Protection", util.OrDash(string(issuer.TokenValidation.ReplayProtection))}, + {"Security Version", fmt.Sprintf("%d", issuer.SecurityVersion)}, + {"Created By User ID", util.OrDash(issuer.CreatedByUserID)}, + {"Archived At", util.FormatLocal(issuer.ArchivedAt)}, + {"Created At", util.FormatLocal(issuer.CreatedAt)}, + {"Updated At", util.FormatLocal(issuer.UpdatedAt)}, + } + PrintTableNoPad(rows, true) +} + +func formatOptionalPositiveInt(value int64) string { + if value == 0 { + return "-" + } + return fmt.Sprintf("%d", value) +} + +var workloadIdentityIssuersCmd = &cobra.Command{ + Use: "issuers", + Aliases: []string{"issuer"}, + Short: "Manage trusted workload identity issuers", + Long: "Manage trusted external identity providers whose signed tokens Kernel can exchange for short-lived API keys. " + + "Reading requires a signed-in organization member; mutations require credential administrator access.", + Run: func(cmd *cobra.Command, args []string) { _ = cmd.Help() }, +} + +var workloadIdentityIssuersListCmd = &cobra.Command{ + Use: "list", + Short: "List workload identity issuer records", + Long: "List workload identity issuers. Search matches name or description case-insensitively and matches an exact issuer ID. " + + "Any signed-in organization member can read this; Kernel API keys cannot.", + Args: cobra.NoArgs, + RunE: runWorkloadIdentityIssuersList, +} + +var workloadIdentityIssuersGetCmd = &cobra.Command{ + Use: "get ", + Short: "Get a workload identity issuer", + Long: "Get a workload identity issuer by its stable resource ID. Any signed-in organization member can read this; Kernel API keys cannot.", + Args: cobra.ExactArgs(1), + RunE: runWorkloadIdentityIssuersGet, +} + +var workloadIdentityIssuersCreateCmd = &cobra.Command{ + Use: "create --name ", + Short: "Create a workload identity issuer", + Long: "Create a trusted workload identity issuer. Organization credential administrator access is required; no external namespace-ownership or staff approval is required. " + + "GitHub Actions and Google Cloud can use their fixed issuer defaults. For discovery, explicit URL, or inline keys, set --jwks-type and the corresponding JWKS flags. " + + "New issuers are disabled unless --enabled is set.", + Args: cobra.NoArgs, + RunE: runWorkloadIdentityIssuersCreate, +} + +var workloadIdentityIssuersUpdateCmd = &cobra.Command{ + Use: "update --expected-version ", + Short: "Update a workload identity issuer", + Long: "Update an issuer using optimistic concurrency. Pass its current security_version as --expected-version. " + + "Whenever any JWKS field is updated, pass --jwks-type as well so the entire key-source object is unambiguous.", + Args: cobra.ExactArgs(1), + RunE: runWorkloadIdentityIssuersUpdate, +} + +var workloadIdentityIssuersDeleteCmd = &cobra.Command{ + Use: "delete ", + Aliases: []string{"archive"}, + Short: "Archive a workload identity issuer", + Long: "Archive an issuer. This retains history and invalidates associated authority within the documented status bound; it does not delete browser resources created through the issuer.", + Args: cobra.ExactArgs(1), + RunE: runWorkloadIdentityIssuersDelete, +} + +var workloadIdentityIssuersVerifyCmd = &cobra.Command{ + Use: "verify ", + Short: "Fetch and verify an issuer's signing keys", + Long: "Check issuer discovery and public verification keys. This read-only operation does not enable trust, approve namespace ownership, create a grant, or issue credentials.", + Args: cobra.ExactArgs(1), + RunE: runWorkloadIdentityIssuersVerify, +} + +func addWorkloadIdentityIssuerMutationFlags(cmd *cobra.Command, update bool) { + addJSONOutputFlag(cmd) + cmd.Flags().String("name", "", "Issuer name; starts with a letter or number and contains only letters, numbers, and hyphens") + cmd.Flags().String("description", "", "Description (maximum 4096 characters); on update, pass an empty string to clear it") + cmd.Flags().String("issuer-url", "", "Exact expected signed issuer URL (maximum 2048 characters)") + cmd.Flags().String("preset-type", "", "Identity provider type: github_actions, aws, google_cloud, microsoft_entra, kubernetes, or custom_oidc") + cmd.Flags().Bool("enabled", false, "Whether this issuer may issue credentials") + cmd.Flags().String("jwks-type", "", "Signing-key source: discovery, explicit_url, or inline") + cmd.Flags().String("jwks-url", "", "Explicit JWKS URL (maximum 2048 characters)") + cmd.Flags().String("jwks-discovery-base-url", "", "Base URL used for OpenID Connect discovery (maximum 2048 characters)") + cmd.Flags().String("jwks-ca-cert-pem", "", "Optional PEM public CA certificates trusted instead of system roots (maximum 65536 characters)") + cmd.Flags().String("jwks-keys", "", "Inline JWK set as a JSON array of 1-16 public JWK objects") + cmd.Flags().Int64("token-max-lifetime-seconds", 0, "Maximum incoming exp minus iat, from 1 to 86400 seconds") + cmd.Flags().String("token-replay-protection", "", "Incoming token reuse policy: single_use or allow_reuse") + if update { + cmd.Flags().Int64("expected-version", 0, "Current security_version used for optimistic concurrency (required)") + _ = cmd.MarkFlagRequired("expected-version") + } else { + _ = cmd.MarkFlagRequired("name") + } +} + +func init() { + addJSONOutputFlag(workloadIdentityIssuersListCmd) + workloadIdentityIssuersListCmd.Flags().Int("page", 1, "Page number (1-based)") + workloadIdentityIssuersListCmd.Flags().Int("per-page", 20, "Items per page (1-99; default 20)") + workloadIdentityIssuersListCmd.Flags().String("query", "", "Case-insensitive search by name or description; an exact issuer ID also matches (maximum 256 characters)") + workloadIdentityIssuersListCmd.Flags().String("status", "", "Filter by lifecycle status: active, archived, or all") + workloadIdentityIssuersListCmd.Flags().Bool("enabled", false, "Filter by whether the issuer is enabled; pass --enabled=false explicitly to select disabled issuers") + + addJSONOutputFlag(workloadIdentityIssuersGetCmd) + addWorkloadIdentityIssuerMutationFlags(workloadIdentityIssuersCreateCmd, false) + addWorkloadIdentityIssuerMutationFlags(workloadIdentityIssuersUpdateCmd, true) + workloadIdentityIssuersDeleteCmd.Flags().BoolP("yes", "y", false, "Skip confirmation prompt") + addJSONOutputFlag(workloadIdentityIssuersVerifyCmd) + + workloadIdentityIssuersCmd.AddCommand( + workloadIdentityIssuersListCmd, + workloadIdentityIssuersGetCmd, + workloadIdentityIssuersCreateCmd, + workloadIdentityIssuersUpdateCmd, + workloadIdentityIssuersDeleteCmd, + workloadIdentityIssuersVerifyCmd, + ) + workloadIdentityCmd.AddCommand(workloadIdentityIssuersCmd) +} + +func getWorkloadIdentityIssuersHandler(cmd *cobra.Command) WorkloadIdentityIssuersCmd { + client := getKernelClient(cmd) + return WorkloadIdentityIssuersCmd{issuers: &client.WorkloadIdentityIssuers, prompter: interactive.NewPrompter()} +} + +func workloadIdentityKeySourceInputFromFlags(cmd *cobra.Command) WorkloadIdentityKeySourceInput { + keyType, _ := cmd.Flags().GetString("jwks-type") + url, _ := cmd.Flags().GetString("jwks-url") + discovery, _ := cmd.Flags().GetString("jwks-discovery-base-url") + caCert, _ := cmd.Flags().GetString("jwks-ca-cert-pem") + keys, _ := cmd.Flags().GetString("jwks-keys") + result := WorkloadIdentityKeySourceInput{Type: keyType} + if cmd.Flags().Changed("jwks-url") { + result.URL = &url + } + if cmd.Flags().Changed("jwks-discovery-base-url") { + result.DiscoveryBaseURL = &discovery + } + if cmd.Flags().Changed("jwks-ca-cert-pem") { + result.CACertPEM = &caCert + } + if cmd.Flags().Changed("jwks-keys") { + result.KeysJSON = &keys + } + result.Set = cmd.Flags().Changed("jwks-type") || result.URL != nil || result.DiscoveryBaseURL != nil || result.CACertPEM != nil || result.KeysJSON != nil + return result +} + +func workloadIdentityTokenValidationInputFromFlags(cmd *cobra.Command) WorkloadIdentityTokenValidationInput { + maxLifetime, _ := cmd.Flags().GetInt64("token-max-lifetime-seconds") + replay, _ := cmd.Flags().GetString("token-replay-protection") + result := WorkloadIdentityTokenValidationInput{ + MaxLifetimeSeconds: Int64Flag{Set: cmd.Flags().Changed("token-max-lifetime-seconds"), Value: maxLifetime}, + } + if cmd.Flags().Changed("token-replay-protection") { + result.ReplayProtection = &replay + } + result.Set = result.MaxLifetimeSeconds.Set || result.ReplayProtection != nil + return result +} + +func runWorkloadIdentityIssuersList(cmd *cobra.Command, args []string) error { + page, _ := cmd.Flags().GetInt("page") + perPage, _ := cmd.Flags().GetInt("per-page") + query, _ := cmd.Flags().GetString("query") + status, _ := cmd.Flags().GetString("status") + output, _ := cmd.Flags().GetString("output") + return getWorkloadIdentityIssuersHandler(cmd).List(cmd.Context(), WorkloadIdentityIssuersListInput{ + Page: page, PerPage: perPage, Query: query, Status: status, Enabled: readBoolFlag(cmd.Flags(), "enabled"), Output: output, + }) +} + +func runWorkloadIdentityIssuersGet(cmd *cobra.Command, args []string) error { + output, _ := cmd.Flags().GetString("output") + return getWorkloadIdentityIssuersHandler(cmd).Get(cmd.Context(), WorkloadIdentityIssuerGetInput{ID: args[0], Output: output}) +} + +func runWorkloadIdentityIssuersCreate(cmd *cobra.Command, args []string) error { + name, _ := cmd.Flags().GetString("name") + description, _ := cmd.Flags().GetString("description") + issuerURL, _ := cmd.Flags().GetString("issuer-url") + presetType, _ := cmd.Flags().GetString("preset-type") + output, _ := cmd.Flags().GetString("output") + var issuerURLPtr, presetTypePtr *string + if cmd.Flags().Changed("issuer-url") { + issuerURLPtr = &issuerURL + } + if cmd.Flags().Changed("preset-type") { + presetTypePtr = &presetType + } + return getWorkloadIdentityIssuersHandler(cmd).Create(cmd.Context(), WorkloadIdentityIssuerCreateInput{ + Name: name, Description: description, IssuerURL: issuerURLPtr, PresetType: presetTypePtr, + Enabled: readBoolFlag(cmd.Flags(), "enabled"), JWKS: workloadIdentityKeySourceInputFromFlags(cmd), + TokenValidation: workloadIdentityTokenValidationInputFromFlags(cmd), Output: output, + }) +} + +func runWorkloadIdentityIssuersUpdate(cmd *cobra.Command, args []string) error { + expectedVersion, _ := cmd.Flags().GetInt64("expected-version") + name, _ := cmd.Flags().GetString("name") + description, _ := cmd.Flags().GetString("description") + issuerURL, _ := cmd.Flags().GetString("issuer-url") + presetType, _ := cmd.Flags().GetString("preset-type") + output, _ := cmd.Flags().GetString("output") + var namePtr, descriptionPtr, issuerURLPtr, presetTypePtr *string + if cmd.Flags().Changed("name") { + namePtr = &name + } + if cmd.Flags().Changed("description") { + descriptionPtr = &description + } + if cmd.Flags().Changed("issuer-url") { + issuerURLPtr = &issuerURL + } + if cmd.Flags().Changed("preset-type") { + presetTypePtr = &presetType + } + return getWorkloadIdentityIssuersHandler(cmd).Update(cmd.Context(), WorkloadIdentityIssuerUpdateInput{ + ID: args[0], ExpectedVersion: expectedVersion, Name: namePtr, Description: descriptionPtr, IssuerURL: issuerURLPtr, + PresetType: presetTypePtr, Enabled: readBoolFlag(cmd.Flags(), "enabled"), JWKS: workloadIdentityKeySourceInputFromFlags(cmd), + TokenValidation: workloadIdentityTokenValidationInputFromFlags(cmd), Output: output, + }) +} + +func runWorkloadIdentityIssuersDelete(cmd *cobra.Command, args []string) error { + yes, _ := cmd.Flags().GetBool("yes") + return getWorkloadIdentityIssuersHandler(cmd).Delete(cmd.Context(), WorkloadIdentityIssuerDeleteInput{ID: args[0], SkipConfirm: yes}) +} + +func runWorkloadIdentityIssuersVerify(cmd *cobra.Command, args []string) error { + output, _ := cmd.Flags().GetString("output") + return getWorkloadIdentityIssuersHandler(cmd).Verify(cmd.Context(), WorkloadIdentityIssuerVerifyInput{ID: args[0], Output: output}) +} diff --git a/cmd/workload_identity_test.go b/cmd/workload_identity_test.go new file mode 100644 index 00000000..3527650b --- /dev/null +++ b/cmd/workload_identity_test.go @@ -0,0 +1,267 @@ +package cmd + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "testing" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/option" + "github.com/spf13/cobra" + "github.com/spf13/pflag" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestWorkloadIdentityCommandMethodCoverage(t *testing.T) { + assertCommandNames(t, serviceAccountsCmd, []string{"create", "delete", "get", "list", "update"}) + assertCommandNames(t, workloadIdentityCmd, []string{"authentication-events", "federation-rules", "issuers"}) + assertCommandNames(t, workloadIdentityIssuersCmd, []string{"create", "delete", "get", "list", "update", "verify"}) + assertCommandNames(t, workloadIdentityFederationRulesCmd, []string{"create", "delete", "get", "list", "update"}) + assertCommandNames(t, workloadIdentityAuthenticationEventsCmd, []string{"list"}) +} + +func TestWorkloadIdentityCommandParameterCoverage(t *testing.T) { + assertLocalFlags(t, serviceAccountsCreateCmd, []string{"description", "name", "output"}) + assertLocalFlags(t, serviceAccountsUpdateCmd, []string{"description", "expected-version", "name", "output"}) + assertLocalFlags(t, serviceAccountsListCmd, []string{"output", "page", "per-page", "query", "status"}) + + issuerMutationFlags := []string{ + "description", "enabled", "issuer-url", "jwks-ca-cert-pem", "jwks-discovery-base-url", "jwks-keys", "jwks-type", "jwks-url", + "name", "output", "preset-type", "token-max-lifetime-seconds", "token-replay-protection", + } + assertLocalFlags(t, workloadIdentityIssuersCreateCmd, issuerMutationFlags) + assertLocalFlags(t, workloadIdentityIssuersUpdateCmd, append(append([]string{}, issuerMutationFlags...), "expected-version")) + assertLocalFlags(t, workloadIdentityIssuersListCmd, []string{"enabled", "output", "page", "per-page", "query", "status"}) + + ruleMutationFlags := []string{ + "description", "enabled", "expected-audience", "issuer-id", "match-claim", "match-environment", "match-event-name", + "match-job-workflow-ref", "match-namespace", "match-ref", "match-repository", "match-repository-id", "match-repository-owner-id", + "match-service-account", "match-subject", "match-subject-prefix", "match-type", "match-workflow", "match-workflow-ref", + "max-token-ttl-seconds", "name", "output", "policy", "project-id", "service-account-id", "token-audience", + } + assertLocalFlags(t, workloadIdentityFederationRulesCreateCmd, ruleMutationFlags) + assertLocalFlags(t, workloadIdentityFederationRulesUpdateCmd, append(append([]string{}, ruleMutationFlags...), "expected-version")) + assertLocalFlags(t, workloadIdentityFederationRulesListCmd, []string{ + "issuer-id", "output", "page", "per-page", "project-id", "query", "service-account-id", "status", + }) + assertLocalFlags(t, workloadIdentityAuthenticationEventsListCmd, []string{ + "end-time", "federation-rule-id", "issuer-id", "outcome", "output", "page", "per-page", "project-id", "service-account-id", "start-time", + }) +} + +func TestWorkloadIdentityListQueryMapping(t *testing.T) { + t.Run("service accounts", func(t *testing.T) { + capturePtermOutput(t) + server := newWorkloadIdentityListServer(t, "/org/service_accounts", map[string]string{ + "limit": "3", "offset": "4", "query": "deploy", "status": "all", + }) + defer server.Close() + client := kernel.NewClient(option.WithBaseURL(server.URL), option.WithAPIKey("test"), option.WithMaxRetries(0)) + err := (ServiceAccountsCmd{serviceAccounts: &client.ServiceAccounts}).List(context.Background(), ServiceAccountsListInput{ + Page: 3, PerPage: 2, Query: "deploy", Status: "all", + }) + require.NoError(t, err) + }) + + t.Run("issuers", func(t *testing.T) { + capturePtermOutput(t) + server := newWorkloadIdentityListServer(t, "/org/workload_identity_issuers", map[string]string{ + "limit": "4", "offset": "3", "query": "github", "status": "archived", "enabled": "false", + }) + defer server.Close() + client := kernel.NewClient(option.WithBaseURL(server.URL), option.WithAPIKey("test"), option.WithMaxRetries(0)) + err := (WorkloadIdentityIssuersCmd{issuers: &client.WorkloadIdentityIssuers}).List(context.Background(), WorkloadIdentityIssuersListInput{ + Page: 2, PerPage: 3, Query: "github", Status: "archived", Enabled: BoolFlag{Set: true, Value: false}, + }) + require.NoError(t, err) + }) + + t.Run("federation rules", func(t *testing.T) { + capturePtermOutput(t) + server := newWorkloadIdentityListServer(t, "/org/workload_identity_federation_rules", map[string]string{ + "limit": "5", "offset": "4", "issuer_id": "iss_123", "project_id": "proj_123", "query": "release", + "service_account_id": "sa_123", "status": "active", + }) + defer server.Close() + client := kernel.NewClient(option.WithBaseURL(server.URL), option.WithAPIKey("test"), option.WithMaxRetries(0)) + err := (WorkloadIdentityFederationRulesCmd{rules: &client.WorkloadIdentityFederationRules}).List(context.Background(), WorkloadIdentityFederationRulesListInput{ + Page: 2, PerPage: 4, IssuerID: "iss_123", ProjectID: "proj_123", Query: "release", ServiceAccountID: "sa_123", Status: "active", + }) + require.NoError(t, err) + }) + + t.Run("authentication events", func(t *testing.T) { + capturePtermOutput(t) + server := newWorkloadIdentityListServer(t, "/org/workload_identity_authentication_events", map[string]string{ + "limit": "6", "offset": "5", "issuer_id": "iss_123", "federation_rule_id": "rule_123", + "service_account_id": "sa_123", "project_id": "proj_123", "outcome": "failure", + "start_time": "2026-01-01T00:00:00Z", "end_time": "2026-01-02T00:00:00Z", + }) + defer server.Close() + client := kernel.NewClient(option.WithBaseURL(server.URL), option.WithAPIKey("test"), option.WithMaxRetries(0)) + err := (WorkloadIdentityAuthenticationEventsCmd{events: &client.WorkloadIdentityAuthenticationEvents}).List(context.Background(), WorkloadIdentityAuthenticationEventsListInput{ + Page: 2, PerPage: 5, IssuerID: "iss_123", FederationRuleID: "rule_123", ServiceAccountID: "sa_123", + ProjectID: "proj_123", Outcome: "failure", StartTime: "2026-01-01T00:00:00Z", EndTime: "2026-01-02T00:00:00Z", + }) + require.NoError(t, err) + }) +} + +func TestBuildWorkloadIdentityIssuerNestedParams(t *testing.T) { + url := "https://issuer.example/jwks.json" + discovery := "https://issuer.example" + ca := "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" + keys := `[{"kty":"RSA","kid":"one","n":"abc","e":"AQAB"}]` + jwks, set, err := buildWorkloadIdentityKeySource(WorkloadIdentityKeySourceInput{ + Set: true, Type: "inline", URL: &url, DiscoveryBaseURL: &discovery, CACertPEM: &ca, KeysJSON: &keys, + }) + require.NoError(t, err) + assert.True(t, set) + payload := marshalParamObject(t, jwks) + assert.Equal(t, "inline", payload["type"]) + assert.Equal(t, url, payload["url"]) + assert.Equal(t, discovery, payload["discovery_base_url"]) + assert.Equal(t, ca, payload["ca_cert_pem"]) + require.Len(t, payload["keys"], 1) + + replay := "allow_reuse" + validation, set, err := buildWorkloadIdentityTokenValidation(WorkloadIdentityTokenValidationInput{ + Set: true, + MaxLifetimeSeconds: Int64Flag{Set: true, Value: 900}, + ReplayProtection: &replay, + }) + require.NoError(t, err) + assert.True(t, set) + payload = marshalParamObject(t, validation) + assert.Equal(t, float64(900), payload["max_lifetime_seconds"]) + assert.Equal(t, "allow_reuse", payload["replay_protection"]) +} + +func TestBuildWorkloadIdentityRuleNestedParams(t *testing.T) { + subject := "repo:kernel/cli:ref:refs/heads/main" + subjectPrefix := "repo:kernel/" + repository := "kernel/cli" + repositoryID := "123" + repositoryOwnerID := "456" + workflow := "release" + workflowRef := "kernel/cli/.github/workflows/release.yml@refs/heads/main" + jobWorkflowRef := "kernel/shared/.github/workflows/deploy.yml@refs/heads/main" + ref := "refs/heads/main" + environment := "production" + namespace := "default" + serviceAccount := "deployer" + match, set, err := buildWorkloadIdentityMatch(WorkloadIdentityMatchInput{ + Set: true, Type: "github_actions", Subject: &subject, SubjectPrefix: &subjectPrefix, + Claims: map[string]string{"/actor_id": "1234"}, ClaimsSet: true, + Repository: &repository, RepositoryID: &repositoryID, RepositoryOwnerID: &repositoryOwnerID, + Workflow: &workflow, WorkflowRef: &workflowRef, JobWorkflowRef: &jobWorkflowRef, Ref: &ref, + Environment: &environment, EventNames: []string{"push", "workflow_dispatch"}, EventNamesSet: true, + Namespace: &namespace, ServiceAccount: &serviceAccount, + }) + require.NoError(t, err) + assert.True(t, set) + payload := marshalParamObject(t, match) + assert.Equal(t, "github_actions", payload["type"]) + assert.Equal(t, subject, payload["subject"]) + assert.Equal(t, subjectPrefix, payload["subject_prefix"]) + assert.Equal(t, repository, payload["repository"]) + assert.Equal(t, repositoryID, payload["repository_id"]) + assert.Equal(t, repositoryOwnerID, payload["repository_owner_id"]) + assert.Equal(t, workflow, payload["workflow"]) + assert.Equal(t, workflowRef, payload["workflow_ref"]) + assert.Equal(t, jobWorkflowRef, payload["job_workflow_ref"]) + assert.Equal(t, ref, payload["ref"]) + assert.Equal(t, environment, payload["environment"]) + assert.Equal(t, namespace, payload["namespace"]) + assert.Equal(t, serviceAccount, payload["service_account"]) + assert.Equal(t, map[string]any{"/actor_id": "1234"}, payload["claims"]) + assert.Equal(t, []any{"push", "workflow_dispatch"}, payload["event_names"]) + + authorization, set, err := buildWorkloadIdentityAuthorization(WorkloadIdentityAuthorizationInput{ + Set: true, + ProjectID: "proj_123", + Policy: `{"statements":[{"action":"browsers:use","resource":"projects/proj_123/browsers/*"}]}`, + PolicySet: true, + TokenAudience: "https://api.kernel.sh", + MaxTokenTTLSeconds: Int64Flag{ + Set: true, Value: 300, + }, + }) + require.NoError(t, err) + assert.True(t, set) + payload = marshalParamObject(t, authorization) + assert.Equal(t, "proj_123", payload["project_id"]) + assert.Equal(t, "https://api.kernel.sh", payload["token_audience"]) + assert.Equal(t, float64(300), payload["max_token_ttl_seconds"]) + policy, ok := payload["policy"].(map[string]any) + require.True(t, ok) + statements, ok := policy["statements"].([]any) + require.True(t, ok) + require.Len(t, statements, 1) +} + +func TestWorkloadIdentityValidationMatchesSpecBounds(t *testing.T) { + _, _, err := buildWorkloadIdentityKeySource(WorkloadIdentityKeySourceInput{Set: true, Type: "inline", KeysJSON: stringPointer(`[null]`)}) + require.Error(t, err) + assert.Contains(t, err.Error(), "not null") + + _, _, err = buildWorkloadIdentityTokenValidation(WorkloadIdentityTokenValidationInput{ + Set: true, MaxLifetimeSeconds: Int64Flag{Set: true, Value: 86401}, + }) + require.Error(t, err) + assert.Contains(t, err.Error(), "86400") + + _, _, err = buildWorkloadIdentityAuthorization(WorkloadIdentityAuthorizationInput{ + Set: true, ProjectID: "proj_123", Policy: `{"statements":[{"action":"browsers:use","resource":"projects/proj_123/browsers/*"}]}`, + PolicySet: true, TokenAudience: "aud", MaxTokenTTLSeconds: Int64Flag{Set: true, Value: 601}, + }) + require.Error(t, err) + assert.Contains(t, err.Error(), "600") +} + +func newWorkloadIdentityListServer(t *testing.T, expectedPath string, expectedQuery map[string]string) *httptest.Server { + t.Helper() + return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) { + assert.Equal(t, expectedPath, request.URL.Path) + for key, value := range expectedQuery { + assert.Equal(t, value, request.URL.Query().Get(key), key) + } + assert.Len(t, request.URL.Query(), len(expectedQuery)) + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte("[]")) + })) +} + +func assertCommandNames(t *testing.T, command *cobra.Command, expected []string) { + t.Helper() + actual := make([]string, 0, len(command.Commands())) + for _, child := range command.Commands() { + if child.Name() != "help" { + actual = append(actual, child.Name()) + } + } + assert.ElementsMatch(t, expected, actual) +} + +func assertLocalFlags(t *testing.T, command *cobra.Command, expected []string) { + t.Helper() + actual := []string{} + command.LocalNonPersistentFlags().VisitAll(func(flag *pflag.Flag) { + actual = append(actual, flag.Name) + }) + assert.ElementsMatch(t, expected, actual) +} + +func marshalParamObject(t *testing.T, value any) map[string]any { + t.Helper() + data, err := json.Marshal(value) + require.NoError(t, err) + var payload map[string]any + require.NoError(t, json.Unmarshal(data, &payload)) + return payload +} + +func stringPointer(value string) *string { return &value } diff --git a/go.mod b/go.mod index aa26ffb6..71da086e 100644 --- a/go.mod +++ b/go.mod @@ -9,7 +9,7 @@ require ( github.com/charmbracelet/lipgloss/v2 v2.0.0-beta.1 github.com/golang-jwt/jwt/v5 v5.2.2 github.com/joho/godotenv v1.5.1 - github.com/kernel/kernel-go-sdk v0.148.0 + github.com/kernel/kernel-go-sdk v0.153.0 github.com/klauspost/compress v1.18.5 github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c github.com/pterm/pterm v0.12.80 diff --git a/go.sum b/go.sum index befa2ec3..65b9e4ee 100644 --- a/go.sum +++ b/go.sum @@ -68,8 +68,8 @@ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0= github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4= -github.com/kernel/kernel-go-sdk v0.148.0 h1:ShpqouDgYdfpCareZgC+YeHQHo+MuTkHYsM/vfAAvHs= -github.com/kernel/kernel-go-sdk v0.148.0/go.mod h1:IoxXdj7vgL3LwtAASaRDhs4qgp9AXwBuB3+3EiRBB+U= +github.com/kernel/kernel-go-sdk v0.153.0 h1:j9nXRESMbpKnhGr0RgGW6ZFw8xSV4+kaoS2ihFE2GAo= +github.com/kernel/kernel-go-sdk v0.153.0/go.mod h1:vAhfZUrC647uk9zju1S62zUqnKN+c3VMi3XJQ83ELsw= github.com/klauspost/compress v1.18.5 h1:/h1gH5Ce+VWNLSWqPzOVn6XBO+vJbCNGvjoaGBFW2IE= github.com/klauspost/compress v1.18.5/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ= github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg= diff --git a/pkg/util/json.go b/pkg/util/json.go index 6a8fccd7..c77be9ca 100644 --- a/pkg/util/json.go +++ b/pkg/util/json.go @@ -81,3 +81,27 @@ func PrintPrettyJSONSlice[T RawJSONProvider](items []T) error { fmt.Println(buf.String()) return nil } + +// PrintPageJSON prints one page of a page-based list as +// {"items": [...], "page": N, "per_page": N, "has_more": bool}, using each item's raw JSON. +func PrintPageJSON[T RawJSONProvider](items []T, page, perPage int, hasMore bool) error { + raw := make([]json.RawMessage, 0, len(items)) + for _, item := range items { + r := item.RawJSON() + if r == "" { + r = "{}" + } + raw = append(raw, json.RawMessage(r)) + } + data, err := json.MarshalIndent(struct { + Items []json.RawMessage `json:"items"` + Page int `json:"page"` + PerPage int `json:"per_page"` + HasMore bool `json:"has_more"` + }{raw, page, perPage, hasMore}, "", " ") + if err != nil { + return err + } + fmt.Println(string(data)) + return nil +}