Add vercel_oauth_app and vercel_oauth_app_client_secret resources (#576)

* Add vercel_oauth_app and vercel_oauth_app_client_secret resources

Adds Terraform support for Sign in with Vercel OAuth applications
(https://vercel.com/docs/sign-in-with-vercel), which until now could only be
created in the dashboard.

vercel_oauth_app manages the application itself: name, slug, description,
home page URI, redirect (callback) URIs, scopes (openid/email/profile/
offline_access), and the consent-page policy URLs. The resource id is the
OAuth client_id. Supports import as [team_id/]client_id. A validator
enforces that an explicitly configured scopes set includes "openid", since
the API force-includes it server-side (omitting it would cause a perpetual
diff); nullable URL fields are cleared with explicit JSON nulls on update.

vercel_oauth_app_client_secret generates a client secret. The API returns
the plaintext exactly once, so it is captured at create time (sensitive) and
subsequently tracked via the secret's last four characters — which is also
how the delete endpoint addresses secrets. Apps allow at most two secrets,
enabling zero-downtime rotation with create_before_destroy. Not importable
by nature.

API notes baked into the client: the get endpoint wraps its response in
{ app }, reports missing apps as HTTP 400 code "invalid_client" rather
than 404 (handled by a dedicated OAuthAppNotFound helper), and the secret
endpoint rejects body-less POSTs with 415, so an empty JSON object is sent.

Both acceptance tests pass against the production API (create, import,
update, secret generation/verification, destroy). Note the API requires the
team Owner role for all mutations, including in acceptance test runs.

* Address review: guard set conversions, add id to client secret resource

- Guard all ElementsAs conversions on redirect_uris/scopes against null AND
  unknown values. Verified empirically that ElementsAs handles a null Set
  fine (yields an empty slice, no diagnostics) — the real hazard is UNKNOWN
  values, which scopes (Optional+Computed) can genuinely be at create time.
  The guards are now uniform across Create and Update, and the acceptance
  test's first step is a minimal config (no redirect_uris, no scopes) so the
  flagged path is exercised for real.
- Add the computed id attribute to vercel_oauth_app_client_secret (Pulumi
  bridge compatibility; fixes TestAllResourcesHaveIDAttribute). The id is the
  API's secret metadata id, resolved from the app's secret list at create
  time, with a synthetic <client_id>/<last_four> fallback should the
  metadata omit it.

Unit tests, staticcheck, tfproviderlint, gofmt -s, and go vet are clean;
both acceptance tests re-verified against the production API.

Author: TooTallNate

client/oauth_app.go

@@ -0,0 +1,189 @@
+package client
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/hashicorp/terraform-plugin-log/tflog"
+)
+
+// OAuthAppNotFound detects the error returned when an OAuth app does not
+// exist. Unusually, the get endpoint reports a missing app as HTTP 400 with
+// code "invalid_client" (the OAuth-style error), while delete uses a plain
+// 404 — treat both as not-found.
+func OAuthAppNotFound(err error) bool {
+	var apiErr APIError
+	return err != nil && errors.As(err, &apiErr) && (apiErr.StatusCode == 404 || apiErr.Code == "invalid_client")
+}
+
+// OAuthAppClientSecretMetadata contains the non-sensitive metadata the API
+// exposes about an OAuth app's client secrets. The secret value itself is only
+// ever returned once, by CreateOAuthAppSecret.
+type OAuthAppClientSecretMetadata struct {
+	ID            string `json:"id"`
+	LastFourChars string `json:"lastFourChars"`
+}
+
+// OAuthApp represents a "Sign in with Vercel" OAuth application.
+type OAuthApp struct {
+	ClientID          string                         `json:"clientId"`
+	TeamID            string                         `json:"teamId"`
+	Name              string                         `json:"name"`
+	Slug              string                         `json:"slug"`
+	Description       string                         `json:"description"`
+	HomePageURI       string                         `json:"homePageUri"`
+	RedirectURIs      []string                       `json:"redirectUris"`
+	Scopes            []string                       `json:"scopes"`
+	PrivacyPolicyURL  string                         `json:"privacyPolicyUrl"`
+	TermsOfServiceURL string                         `json:"termsOfServiceUrl"`
+	CodeOfConductURL  string                         `json:"codeOfConductUrl"`
+	ClientSecrets     []OAuthAppClientSecretMetadata `json:"clientSecrets"`
+}
+
+type CreateOAuthAppRequest struct {
+	TeamID            string   `json:"-"`
+	Name              string   `json:"name"`
+	Slug              string   `json:"slug"`
+	Description       string   `json:"description,omitempty"`
+	HomePageURI       string   `json:"homePageUri,omitempty"`
+	RedirectURIs      []string `json:"redirectUris,omitempty"`
+	Scopes            []string `json:"scopes,omitempty"`
+	PrivacyPolicyURL  string   `json:"privacyPolicyUrl,omitempty"`
+	TermsOfServiceURL string   `json:"termsOfServiceUrl,omitempty"`
+	CodeOfConductURL  string   `json:"codeOfConductUrl,omitempty"`
+}
+
+// UpdateOAuthAppRequest updates an OAuth app. Nullable URL fields are pointers
+// WITHOUT omitempty: an explicit JSON null is how the API clears a previously
+// set value, so unset (nil) pointers are serialized as null deliberately.
+type UpdateOAuthAppRequest struct {
+	TeamID            string   `json:"-"`
+	ClientID          string   `json:"-"`
+	Name              string   `json:"name"`
+	Slug              string   `json:"slug"`
+	Description       string   `json:"description"`
+	HomePageURI       *string  `json:"homePageUri"`
+	RedirectURIs      []string `json:"redirectUris"`
+	Scopes            []string `json:"scopes"`
+	PrivacyPolicyURL  *string  `json:"privacyPolicyUrl"`
+	TermsOfServiceURL *string  `json:"termsOfServiceUrl"`
+	CodeOfConductURL  *string  `json:"codeOfConductUrl"`
+}
+
+// OAuthAppSecret is the response of generating a client secret. This is the
+// ONLY time the API returns the plaintext secret; subsequent reads expose just
+// its last four characters.
+type OAuthAppSecret struct {
+	ClientID     string `json:"clientId"`
+	ClientSecret string `json:"clientSecret"`
+}
+
+func (c *Client) CreateOAuthApp(ctx context.Context, request CreateOAuthAppRequest) (a OAuthApp, err error) {
+	url := fmt.Sprintf("%s/v1/oauth-apps", c.baseURL)
+	if c.TeamID(request.TeamID) != "" {
+		url = fmt.Sprintf("%s?teamId=%s", url, c.TeamID(request.TeamID))
+	}
+	payload := string(mustMarshal(request))
+	tflog.Info(ctx, "creating oauth app", map[string]any{
+		"url":     url,
+		"payload": payload,
+	})
+	err = c.doRequest(clientRequest{
+		ctx:    ctx,
+		method: "POST",
+		url:    url,
+		body:   payload,
+	}, &a)
+	return a, err
+}
+
+func (c *Client) GetOAuthApp(ctx context.Context, clientID, teamID string) (OAuthApp, error) {
+	url := fmt.Sprintf("%s/v1/oauth-apps/%s", c.baseURL, clientID)
+	if c.TeamID(teamID) != "" {
+		url = fmt.Sprintf("%s?teamId=%s", url, c.TeamID(teamID))
+	}
+	tflog.Info(ctx, "getting oauth app", map[string]any{
+		"url": url,
+	})
+	// Unlike create/update, the get endpoint wraps the app in an envelope.
+	var response struct {
+		App OAuthApp `json:"app"`
+	}
+	err := c.doRequest(clientRequest{
+		ctx:    ctx,
+		method: "GET",
+		url:    url,
+	}, &response)
+	return response.App, err
+}
+
+func (c *Client) UpdateOAuthApp(ctx context.Context, request UpdateOAuthAppRequest) (a OAuthApp, err error) {
+	url := fmt.Sprintf("%s/v1/oauth-apps/%s", c.baseURL, request.ClientID)
+	if c.TeamID(request.TeamID) != "" {
+		url = fmt.Sprintf("%s?teamId=%s", url, c.TeamID(request.TeamID))
+	}
+	payload := string(mustMarshal(request))
+	tflog.Info(ctx, "updating oauth app", map[string]any{
+		"url":     url,
+		"payload": payload,
+	})
+	err = c.doRequest(clientRequest{
+		ctx:    ctx,
+		method: "PATCH",
+		url:    url,
+		body:   payload,
+	}, &a)
+	return a, err
+}
+
+func (c *Client) DeleteOAuthApp(ctx context.Context, clientID, teamID string) error {
+	url := fmt.Sprintf("%s/v1/oauth-apps/%s", c.baseURL, clientID)
+	if c.TeamID(teamID) != "" {
+		url = fmt.Sprintf("%s?teamId=%s", url, c.TeamID(teamID))
+	}
+	tflog.Info(ctx, "deleting oauth app", map[string]any{
+		"url": url,
+	})
+	return c.doRequest(clientRequest{
+		ctx:    ctx,
+		method: "DELETE",
+		url:    url,
+	}, nil)
+}
+
+func (c *Client) CreateOAuthAppSecret(ctx context.Context, clientID, teamID string) (s OAuthAppSecret, err error) {
+	url := fmt.Sprintf("%s/v1/oauth-apps/%s/secret", c.baseURL, clientID)
+	if c.TeamID(teamID) != "" {
+		url = fmt.Sprintf("%s?teamId=%s", url, c.TeamID(teamID))
+	}
+	tflog.Info(ctx, "creating oauth app client secret", map[string]any{
+		"url": url,
+	})
+	// The endpoint takes no parameters but rejects body-less requests with
+	// 415 Unsupported Media Type — send an empty JSON object.
+	err = c.doRequest(clientRequest{
+		ctx:    ctx,
+		method: "POST",
+		url:    url,
+		body:   "{}",
+	}, &s)
+	return s, err
+}
+
+// DeleteOAuthAppSecret deletes a client secret. The API identifies secrets by
+// the LAST FOUR CHARACTERS of the secret value, not by id.
+func (c *Client) DeleteOAuthAppSecret(ctx context.Context, clientID, lastFourChars, teamID string) error {
+	url := fmt.Sprintf("%s/v1/oauth-apps/%s/secret/%s", c.baseURL, clientID, lastFourChars)
+	if c.TeamID(teamID) != "" {
+		url = fmt.Sprintf("%s?teamId=%s", url, c.TeamID(teamID))
+	}
+	tflog.Info(ctx, "deleting oauth app client secret", map[string]any{
+		"url": url,
+	})
+	return c.doRequest(clientRequest{
+		ctx:    ctx,
+		method: "DELETE",
+		url:    url,
+	}, nil)
+}

docs/resources/oauth_app.md

@@ -0,0 +1,78 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "vercel_oauth_app Resource - terraform-provider-vercel"
+subcategory: ""
+description: |-
+  Provides an OAuth App resource for Sign in with Vercel https://vercel.com/docs/sign-in-with-vercel.
+  An OAuth App lets people use their Vercel account to log in to your application via OAuth 2.0 / OpenID Connect. Use the vercel_oauth_app_client_secret resource to generate the client secret your application authenticates with.
+  ~> Managing OAuth Apps requires the Owner role on the team.
+---
+
+# vercel_oauth_app (Resource)
+
+Provides an OAuth App resource for [Sign in with Vercel](https://vercel.com/docs/sign-in-with-vercel).
+
+An OAuth App lets people use their Vercel account to log in to your application via OAuth 2.0 / OpenID Connect. Use the `vercel_oauth_app_client_secret` resource to generate the client secret your application authenticates with.
+
+~> Managing OAuth Apps requires the Owner role on the team.
+
+## Example Usage
+
+```terraform
+resource "vercel_oauth_app" "example" {
+  name = "My Example App"
+  slug = "my-example-app"
+
+  description   = "Lets users sign in to Example with their Vercel account."
+  home_page_uri = "https://example.com"
+
+  redirect_uris = [
+    "https://example.com/api/auth/callback",
+    "http://localhost:3000/api/auth/callback",
+  ]
+
+  # "openid" is always required; "offline_access" issues refresh tokens.
+  scopes = ["openid", "email", "profile", "offline_access"]
+
+  privacy_policy_url   = "https://example.com/privacy"
+  terms_of_service_url = "https://example.com/terms"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `name` (String) A human-readable name for the OAuth App, shown on the consent page.
+- `slug` (String) A URL-friendly slug for the OAuth App. Must be unique.
+
+### Optional
+
+- `code_of_conduct_url` (String) The URL of the application's code of conduct.
+- `description` (String) A description of the OAuth App, shown on the consent page.
+- `home_page_uri` (String) The URL of the application's home page.
+- `privacy_policy_url` (String) The URL of the application's privacy policy, shown on the consent page.
+- `redirect_uris` (Set of String) The authorization callback URLs of the OAuth App. Must be absolute `https` URLs (`http` is allowed for loopback addresses only).
+- `scopes` (Set of String) The scopes the OAuth App may request: `openid` (always required), `email`, `profile`, and `offline_access` (issues refresh tokens). Defaults to `["openid"]`.
+- `team_id` (String) The ID of the team the OAuth App should exist under. Required when configuring a team resource if a default team has not been set in the provider.
+- `terms_of_service_url` (String) The URL of the application's terms of service, shown on the consent page.
+
+### Read-Only
+
+- `id` (String) The client ID of the OAuth App (`cl_...`). Use this as the OAuth `client_id`.
+
+## Import
+
+Import is supported using the following syntax:
+
+The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example:
+
+```shell
+# If importing into a personal account, or with a team configured on
+# the provider, simply use the client_id.
+terraform import vercel_oauth_app.example cl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# If importing to a team, use the team_id and client_id.
+terraform import vercel_oauth_app.example team_xxxxxxxxxxxxxxxxxxxxxxxx/cl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```

docs/resources/oauth_app_client_secret.md

@@ -0,0 +1,80 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "vercel_oauth_app_client_secret Resource - terraform-provider-vercel"
+subcategory: ""
+description: |-
+  Provides a client secret for a vercel_oauth_app (Sign in with Vercel https://vercel.com/docs/sign-in-with-vercel).
+  The secret value is only ever returned by the API at creation time and is stored (marked sensitive) in the Terraform state. An OAuth App can have at most two client secrets at a time, so zero-downtime rotation is possible by creating a new secret before destroying the old one (e.g. with terraform apply -replace and create_before_destroy).
+  ~> Managing client secrets requires the Owner role on the team.
+  -> This resource cannot be imported, as the API never re-exposes the secret value.
+---
+
+# vercel_oauth_app_client_secret (Resource)
+
+Provides a client secret for a `vercel_oauth_app` ([Sign in with Vercel](https://vercel.com/docs/sign-in-with-vercel)).
+
+The secret value is only ever returned by the API at creation time and is stored (marked sensitive) in the Terraform state. An OAuth App can have at most two client secrets at a time, so zero-downtime rotation is possible by creating a new secret before destroying the old one (e.g. with `terraform apply -replace` and `create_before_destroy`).
+
+~> Managing client secrets requires the Owner role on the team.
+
+-> This resource cannot be imported, as the API never re-exposes the secret value.
+
+## Example Usage
+
+```terraform
+resource "vercel_oauth_app" "example" {
+  name = "My Example App"
+  slug = "my-example-app"
+
+  redirect_uris = ["https://example.com/api/auth/callback"]
+  scopes        = ["openid", "email", "profile", "offline_access"]
+}
+
+resource "vercel_oauth_app_client_secret" "example" {
+  oauth_app_id = vercel_oauth_app.example.id
+
+  # An OAuth App can hold at most two secrets at a time, so a replacement
+  # secret can be created before the old one is destroyed (zero-downtime
+  # rotation with e.g. `terraform apply -replace=vercel_oauth_app_client_secret.example`).
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+
+# Example: feed the credentials to the application consuming them.
+resource "vercel_project_environment_variable" "oauth_client_id" {
+  project_id = vercel_project.example.id
+  key        = "OAUTH_CLIENT_ID"
+  value      = vercel_oauth_app.example.id
+  target     = ["production", "preview", "development"]
+}
+
+resource "vercel_project_environment_variable" "oauth_client_secret" {
+  project_id = vercel_project.example.id
+  key        = "OAUTH_CLIENT_SECRET"
+  value      = vercel_oauth_app_client_secret.example.client_secret
+  target     = ["production", "preview", "development"]
+  sensitive  = true
+}
+
+resource "vercel_project" "example" {
+  name = "example-project"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `oauth_app_id` (String) The client ID of the OAuth App (`cl_...`) to generate a secret for.
+
+### Optional
+
+- `team_id` (String) The ID of the team the OAuth App exists under. Required when configuring a team resource if a default team has not been set in the provider.
+
+### Read-Only
+
+- `client_secret` (String, Sensitive) The generated client secret. Only available at creation time; stored in the Terraform state.
+- `id` (String) The unique identifier of the client secret.
+- `last_four_chars` (String) The last four characters of the client secret — the identifier the Vercel API and dashboard use to reference this secret.

examples/resources/vercel_oauth_app/import.sh

@@ -0,0 +1,6 @@
+# If importing into a personal account, or with a team configured on
+# the provider, simply use the client_id.
+terraform import vercel_oauth_app.example cl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# If importing to a team, use the team_id and client_id.
+terraform import vercel_oauth_app.example team_xxxxxxxxxxxxxxxxxxxxxxxx/cl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

examples/resources/vercel_oauth_app/resource.tf

@@ -0,0 +1,18 @@
+resource "vercel_oauth_app" "example" {
+  name = "My Example App"
+  slug = "my-example-app"
+
+  description   = "Lets users sign in to Example with their Vercel account."
+  home_page_uri = "https://example.com"
+
+  redirect_uris = [
+    "https://example.com/api/auth/callback",
+    "http://localhost:3000/api/auth/callback",
+  ]
+
+  # "openid" is always required; "offline_access" issues refresh tokens.
+  scopes = ["openid", "email", "profile", "offline_access"]
+
+  privacy_policy_url   = "https://example.com/privacy"
+  terms_of_service_url = "https://example.com/terms"
+}