briar-cli 1.1.1__py3-none-any.whl

briar/auth/_acquirers/aws_sso.py

@@ -0,0 +1,185 @@
+"""AWS SSO / IAM Identity Center OIDC device-code acquirer.
+
+Implements the same flow as ``aws sso login`` but vends STS
+credentials directly into briar's env-var convention.
+
+Three-step OIDC dance per the SSO spec:
+  1. RegisterClient   → client_id, client_secret (cache friendly)
+  2. StartDeviceAuthorization → device_code, user_code, verification_uri
+  3. CreateToken (polled) → access_token
+
+Then exchange the SSO access_token for STS credentials via
+``sso.get_role_credentials(account_id, role_name, access_token)``.
+
+Stores AWS_<COMPANY>_ACCESS_KEY_ID, _SECRET_ACCESS_KEY,
+_SESSION_TOKEN, _REGION + records expires_at so the CLI can warn
+the operator about the upcoming rotation."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from briar.auth._acquirer import CredentialAcquirer, Credentials, CredentialExpired
+from briar.auth._prompt import PromptIO
+from briar.env_vars import CredEnv
+
+
+log = logging.getLogger(__name__)
+
+
+class AwsSsoAcquirer(CredentialAcquirer):
+    kind = "aws-sso"
+    display_name = "AWS IAM Identity Center (SSO device-code flow)"
+
+    def acquire(self, *, company: str, prompt: PromptIO) -> Credentials:
+        if not company:
+            raise ValueError("aws-sso: --company is required")
+
+        try:
+            import boto3
+            import botocore.exceptions
+        except ImportError:
+            raise RuntimeError("aws-sso: boto3 not installed — run `pip install briar-cli` (base)")
+
+        prompt.info("==> AWS IAM Identity Center — device flow")
+        start_url = prompt.prompt("    SSO start URL (e.g. https://acme.awsapps.com/start): ").strip()
+        sso_region = prompt.prompt("    SSO region [us-east-1]: ").strip() or "us-east-1"
+        if not start_url:
+            raise ValueError("aws-sso: SSO start URL required")
+
+        oidc = boto3.client("sso-oidc", region_name=sso_region)
+        sso = boto3.client("sso", region_name=sso_region)
+
+        # Step 1: register a client (one-shot per session).
+        reg = oidc.register_client(clientName="briar-cli", clientType="public")
+        client_id = reg["clientId"]
+        client_secret = reg["clientSecret"]
+
+        # Step 2: kick off device auth.
+        device = oidc.start_device_authorization(
+            clientId=client_id,
+            clientSecret=client_secret,
+            startUrl=start_url,
+        )
+        verification_uri = device.get("verificationUriComplete") or device["verificationUri"]
+        user_code = device["userCode"]
+        device_code = device["deviceCode"]
+        interval = int(device.get("interval", 5))
+        expires_in = int(device.get("expiresIn", 600))
+
+        prompt.info(f"    1. Open {verification_uri}")
+        prompt.info(f"    2. Verify the code: {user_code}")
+        prompt.info(f"    3. Approve the briar-cli device")
+        prompt.info(f"    polling every {interval}s for up to {expires_in}s …")
+        prompt.open_url(verification_uri)
+
+        # Step 3: poll for the SSO access token.
+        def _poll_once() -> Optional[Dict[str, Any]]:
+            try:
+                return oidc.create_token(
+                    clientId=client_id,
+                    clientSecret=client_secret,
+                    grantType="urn:ietf:params:oauth:grant-type:device_code",
+                    deviceCode=device_code,
+                )
+            except botocore.exceptions.ClientError as exc:
+                code = exc.response.get("Error", {}).get("Code", "")
+                if code in ("AuthorizationPendingException", "SlowDownException"):
+                    return None
+                raise
+            except Exception as exc:  # noqa: BLE001
+                log.debug("aws-sso poll error: %s", exc)
+                return None
+
+        try:
+            token_resp = prompt.poll(every=interval, max_wait=expires_in, fn=_poll_once)
+        except TimeoutError:
+            raise RuntimeError("aws-sso: timed out waiting for authorisation")
+
+        access_token = token_resp["accessToken"]  # type: ignore[index]
+
+        # Step 4: enumerate accounts/roles the operator has access to.
+        accounts = []
+        for page in sso.get_paginator("list_accounts").paginate(accessToken=access_token):
+            accounts.extend(page.get("accountList", []))
+        if not accounts:
+            raise RuntimeError("aws-sso: no accounts visible to this SSO identity")
+
+        if len(accounts) == 1:
+            account = accounts[0]
+        else:
+            prompt.info("    Multiple accounts available:")
+            for i, a in enumerate(accounts, start=1):
+                prompt.info(f"      [{i}] {a['accountId']}  {a.get('accountName', '')}")
+            idx = int(prompt.prompt("    Select account number: ").strip())
+            account = accounts[idx - 1]
+        account_id = account["accountId"]
+
+        roles = []
+        for page in sso.get_paginator("list_account_roles").paginate(accessToken=access_token, accountId=account_id):
+            roles.extend(page.get("roleList", []))
+        if not roles:
+            raise RuntimeError(f"aws-sso: no roles for account {account_id}")
+        if len(roles) == 1:
+            role = roles[0]
+        else:
+            prompt.info(f"    Roles available for account {account_id}:")
+            for i, r in enumerate(roles, start=1):
+                prompt.info(f"      [{i}] {r['roleName']}")
+            idx = int(prompt.prompt("    Select role number: ").strip())
+            role = roles[idx - 1]
+        role_name = role["roleName"]
+
+        # Step 5: exchange for STS credentials.
+        creds_resp = sso.get_role_credentials(
+            accessToken=access_token,
+            accountId=account_id,
+            roleName=role_name,
+        )
+        rc = creds_resp["roleCredentials"]
+
+        # Expiry is milliseconds since epoch in the SSO response.
+        expires_at_ms = rc.get("expiration")
+        expires_at = datetime.fromtimestamp(int(expires_at_ms) / 1000, tz=timezone.utc) if expires_at_ms else None
+
+        region = prompt.prompt(f"    Default region for {company} extractions [{sso_region}]: ").strip() or sso_region
+
+        return Credentials(
+            provider_kind=self.kind,
+            entries={
+                CredEnv.AWS_KEY_ID.for_company(company): rc["accessKeyId"],
+                CredEnv.AWS_SECRET.for_company(company): rc["secretAccessKey"],
+                CredEnv.AWS_SESSION.for_company(company): rc.get("sessionToken", ""),
+                CredEnv.AWS_REGION.for_company(company): region,
+            },
+            expires_at=expires_at,
+            metadata={
+                "auth_mode": "sso-device",
+                "account_id": account_id,
+                "role_name": role_name,
+                "start_url": start_url,
+                "sso_region": sso_region,
+            },
+        )
+
+    def refresh(self, *, company: str, existing: Credentials) -> Credentials:
+        """SSO refresh requires the operator's still-valid SSO access
+        token (cached in ``~/.aws/sso/cache/`` by `aws sso login`).
+        We don't cache it ourselves yet — punt to a full re-acquire."""
+        raise CredentialExpired(
+            f"aws-sso: refresh not implemented yet — run "
+            f"`briar auth login --provider aws-sso --company {company}` to re-acquire"
+        )
+
+    @classmethod
+    def writes(cls, *, company: str) -> List[str]:
+        if not company:
+            return []
+        return [
+            CredEnv.AWS_KEY_ID.for_company(company),
+            CredEnv.AWS_SECRET.for_company(company),
+            CredEnv.AWS_SESSION.for_company(company),
+            CredEnv.AWS_REGION.for_company(company),
+        ]

briar/auth/_acquirers/aws_static.py

@@ -0,0 +1,54 @@
+"""AWS static-access-key acquirer.
+
+Prompts for AccessKeyId + SecretAccessKey + region. No session
+token (use ``aws-sso`` or external aws-vault/granted for STS-backed
+credentials with auto-rotation)."""
+
+from __future__ import annotations
+
+from typing import List
+
+from briar.auth._acquirer import CredentialAcquirer, Credentials
+from briar.auth._prompt import PromptIO
+from briar.env_vars import CredEnv
+
+
+class AwsStaticAcquirer(CredentialAcquirer):
+    kind = "aws-static"
+    display_name = "AWS static access key (paste)"
+
+    def acquire(self, *, company: str, prompt: PromptIO) -> Credentials:
+        if not company:
+            raise ValueError("aws-static: --company is required")
+        prompt.info("==> AWS static keys")
+        prompt.info("    Paste an IAM user's AccessKeyId + SecretAccessKey.")
+        prompt.info("    The key needs only the permissions briar's extractors call:")
+        prompt.info("      ec2:Describe*  rds:Describe*  ecs:List*+Describe*")
+        prompt.info("      lambda:List*+Get*  logs:Describe*  sqs:List*+Get*")
+        prompt.info("      sts:GetCallerIdentity")
+
+        kid = prompt.prompt("    AccessKeyId (AKIA…): ").strip()
+        secret = prompt.prompt("    SecretAccessKey: ", secret=True).strip()
+        region = prompt.prompt("    Default region [us-east-1]: ").strip() or "us-east-1"
+        if not (kid and secret):
+            raise ValueError("aws-static: key id and secret required")
+
+        return Credentials(
+            provider_kind=self.kind,
+            entries={
+                CredEnv.AWS_KEY_ID.for_company(company): kid,
+                CredEnv.AWS_SECRET.for_company(company): secret,
+                CredEnv.AWS_REGION.for_company(company): region,
+            },
+            metadata={"auth_mode": "static-iam-user"},
+        )
+
+    @classmethod
+    def writes(cls, *, company: str) -> List[str]:
+        if not company:
+            return []
+        return [
+            CredEnv.AWS_KEY_ID.for_company(company),
+            CredEnv.AWS_SECRET.for_company(company),
+            CredEnv.AWS_REGION.for_company(company),
+        ]

briar/auth/_acquirers/bitbucket.py

@@ -0,0 +1,60 @@
+"""Bitbucket Cloud app-password acquirer.
+
+Walks the user through app-password generation at
+bitbucket.org → personal settings → app passwords, then prompts
+for workspace + username + paste of the generated password.
+
+Stores ``BITBUCKET_<COMPANY>_USERNAME``, ``BITBUCKET_<COMPANY>_APP_PASSWORD``,
+``BITBUCKET_<COMPANY>_WORKSPACE`` (per-company because app passwords
+are tied to a user × workspace pair, unlike GitHub PATs)."""
+
+from __future__ import annotations
+
+from typing import List
+
+from briar.auth._acquirer import CredentialAcquirer, Credentials
+from briar.auth._prompt import PromptIO
+from briar.env_vars import CredEnv
+
+
+_SETTINGS_URL = "https://bitbucket.org/account/settings/app-passwords/"
+
+
+class BitbucketAppPasswordAcquirer(CredentialAcquirer):
+    kind = "bitbucket-app-password"
+    display_name = "Bitbucket Cloud app password (paste)"
+
+    def acquire(self, *, company: str, prompt: PromptIO) -> Credentials:
+        if not company:
+            raise ValueError("bitbucket-app-password: --company is required")
+        prompt.info("==> Bitbucket Cloud — app password")
+        prompt.info(f"    1. Open {_SETTINGS_URL}")
+        prompt.info("    2. Click 'Create app password'")
+        prompt.info("    3. Required scopes: Repositories: Read + Write, Pull requests: Read + Write")
+        prompt.info("    4. Copy the generated password (you only see it once)")
+        prompt.open_url(_SETTINGS_URL)
+
+        workspace = prompt.prompt("    Bitbucket workspace slug: ").strip()
+        username = prompt.prompt("    Bitbucket username (NOT email): ").strip()
+        password = prompt.prompt("    paste app password: ", secret=True).strip()
+        if not (workspace and username and password):
+            raise ValueError("bitbucket-app-password: all three fields required")
+
+        return Credentials(
+            provider_kind=self.kind,
+            entries={
+                CredEnv.BITBUCKET_WORKSPACE.for_company(company): workspace,
+                CredEnv.BITBUCKET_USERNAME.for_company(company): username,
+                CredEnv.BITBUCKET_APP_PASSWORD.for_company(company): password,
+            },
+        )
+
+    @classmethod
+    def writes(cls, *, company: str) -> List[str]:
+        if not company:
+            return []
+        return [
+            CredEnv.BITBUCKET_WORKSPACE.for_company(company),
+            CredEnv.BITBUCKET_USERNAME.for_company(company),
+            CredEnv.BITBUCKET_APP_PASSWORD.for_company(company),
+        ]

briar/auth/_acquirers/github_device.py

@@ -0,0 +1,129 @@
+"""GitHub OAuth device flow acquirer.
+
+Implements the device-flow grant against GitHub's OAuth endpoints
+(``github.com/login/device/code`` + ``github.com/login/oauth/access_token``).
+The user visits the verification URL, enters a short code, and the
+CLI polls until authorisation completes. The CLI never sees the
+password — same security shape as ``gh auth login``.
+
+Requires an OAuth App's client_id. Env var: ``BRIAR_GITHUB_CLIENT_ID``
+(global; one OAuth app per briar install). To create one:
+https://github.com/settings/applications/new — set "Device flow"
+to enabled, callback URL can be anything (unused for device flow).
+
+Stores ``GITHUB_TOKEN``."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import urllib.parse
+import urllib.request
+from typing import List
+
+from briar.auth._acquirer import CredentialAcquirer, Credentials
+from briar.auth._prompt import PromptIO
+
+
+log = logging.getLogger(__name__)
+
+_DEVICE_CODE_URL = "https://github.com/login/device/code"
+_TOKEN_URL = "https://github.com/login/oauth/access_token"
+_DEFAULT_SCOPES = "repo,read:org"
+
+
+def _post_form(url: str, fields: dict) -> dict:
+    """POST application/x-www-form-urlencoded with Accept: application/json.
+    Returns parsed JSON. Raises on non-2xx."""
+    data = urllib.parse.urlencode(fields).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=data,
+        headers={"Accept": "application/json", "User-Agent": "briar-cli"},
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        return json.loads(resp.read())
+
+
+class GithubDeviceAcquirer(CredentialAcquirer):
+    kind = "github-device"
+    display_name = "GitHub OAuth device flow"
+
+    def acquire(self, *, company: str, prompt: PromptIO) -> Credentials:
+        client_id = os.environ.get("BRIAR_GITHUB_CLIENT_ID", "").strip()
+        if not client_id:
+            raise RuntimeError(
+                "github-device: BRIAR_GITHUB_CLIENT_ID env var required. "
+                "Register an OAuth App at https://github.com/settings/applications/new "
+                "with 'Device flow' enabled, then export the client_id."
+            )
+
+        # Step 1: request a device code.
+        try:
+            init = _post_form(
+                _DEVICE_CODE_URL,
+                {"client_id": client_id, "scope": _DEFAULT_SCOPES},
+            )
+        except Exception as exc:  # noqa: BLE001
+            raise RuntimeError(f"github-device: device-code request failed: {exc}")
+
+        device_code = init.get("device_code") or ""
+        user_code = init.get("user_code") or ""
+        verification_uri = init.get("verification_uri") or "https://github.com/login/device"
+        interval = max(int(init.get("interval", 5)), 1)
+        expires_in = int(init.get("expires_in", 900))
+
+        if not (device_code and user_code):
+            raise RuntimeError(f"github-device: malformed device-code response: {init}")
+
+        # Step 2: prompt user.
+        prompt.info("==> GitHub OAuth — device flow")
+        prompt.info(f"    1. Open {verification_uri}")
+        prompt.info(f"    2. Enter code: {user_code}")
+        prompt.info(f"    3. Authorise the app (scopes: {_DEFAULT_SCOPES})")
+        prompt.info(f"    polling every {interval}s for up to {expires_in}s …")
+        prompt.open_url(verification_uri)
+
+        # Step 3: poll the token endpoint.
+        def _poll_once():
+            try:
+                resp = _post_form(
+                    _TOKEN_URL,
+                    {
+                        "client_id": client_id,
+                        "device_code": device_code,
+                        "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                    },
+                )
+            except Exception as exc:  # noqa: BLE001
+                log.debug("github-device: poll error (will retry): %s", exc)
+                return None
+            err = resp.get("error", "")
+            # `authorization_pending` is the normal "user hasn't acted yet"
+            # response — keep polling. `slow_down` means double the interval
+            # (rare; servers rarely send it). Other errors abort.
+            if err == "authorization_pending":
+                return None
+            if err == "slow_down":
+                return None
+            if err:
+                raise RuntimeError(f"github-device: OAuth error: {err} — {resp.get('error_description', '')}")
+            token = resp.get("access_token", "")
+            return token or None
+
+        try:
+            token = prompt.poll(every=interval, max_wait=expires_in, fn=_poll_once)
+        except TimeoutError:
+            raise RuntimeError("github-device: timed out waiting for authorisation")
+
+        return Credentials(
+            provider_kind=self.kind,
+            entries={"GITHUB_TOKEN": str(token)},
+            metadata={"scopes": _DEFAULT_SCOPES, "auth_mode": "oauth-device"},
+        )
+
+    @classmethod
+    def writes(cls, *, company: str) -> List[str]:
+        return ["GITHUB_TOKEN"]

briar/auth/_acquirers/github_pat.py

@@ -0,0 +1,44 @@
+"""GitHub PAT (Personal Access Token) acquirer.
+
+Walks the user through manual token generation on github.com →
+settings → developer settings → personal access tokens, then
+prompts for the paste. Stores ``GITHUB_TOKEN`` (no per-company
+suffix — GitHub PATs are workspace-wide in this codebase)."""
+
+from __future__ import annotations
+
+from typing import List
+
+from briar.auth._acquirer import CredentialAcquirer, Credentials
+from briar.auth._prompt import PromptIO
+
+
+_TOKENS_URL = "https://github.com/settings/tokens"
+
+
+class GithubPatAcquirer(CredentialAcquirer):
+    kind = "github-pat"
+    display_name = "GitHub Personal Access Token (paste)"
+
+    def acquire(self, *, company: str, prompt: PromptIO) -> Credentials:
+        prompt.info("==> GitHub PAT — manual token generation")
+        prompt.info(f"    1. Open {_TOKENS_URL}")
+        prompt.info("    2. Click 'Generate new token (classic)'")
+        prompt.info("    3. Required scopes:")
+        prompt.info("         repo               (read PRs, push commits)")
+        prompt.info("         read:org           (org membership for filters)")
+        prompt.info("    4. Set expiration to 90 days (or your org policy)")
+        prompt.info("    5. Copy the token (ghp_… or github_pat_…)")
+        prompt.open_url(_TOKENS_URL)
+        token = prompt.prompt("    paste token: ", secret=True).strip()
+        if not token:
+            raise ValueError("github-pat: empty token")
+        return Credentials(
+            provider_kind=self.kind,
+            entries={"GITHUB_TOKEN": token},
+            metadata={"label": f"briar-{company or 'default'}"},
+        )
+
+    @classmethod
+    def writes(cls, *, company: str) -> List[str]:
+        return ["GITHUB_TOKEN"]

briar/auth/_acquirers/infisical.py

@@ -0,0 +1,80 @@
+"""Infisical machine-identity acquirer — "log into Infisical".
+
+This is the bootstrap-the-bootstrap flow: every other store backend
+authenticates with credentials the operator already has (AWS keys
+in their ~/.aws, Vault token in their shell, GitHub PAT generated
+on github.com). Infisical's machine identity is generated FROM
+within Infisical's web UI, so we walk the operator through that.
+
+The result is THREE values pasted into briar's local store (the
+``envfile`` backend by default — usually ``~/.config/briar/secrets.env``
+on a laptop). Subsequent processes that load that file then have
+``INFISICAL_CLIENT_ID/_SECRET/_PROJECT_ID`` in env, so both
+``InfisicalBootstrap`` (startup hydrate) and ``InfisicalStore``
+(per-name read/write) can talk to Infisical.
+
+Once these are set, ``briar auth login --provider github-pat
+--store infisical`` writes the acquired GitHub PAT INTO Infisical,
+not the local envfile. Same with every other acquirer."""
+
+from __future__ import annotations
+
+from typing import List
+
+from briar.auth._acquirer import CredentialAcquirer, Credentials, DestinationPolicy
+from briar.auth._prompt import PromptIO
+
+
+_MACHINE_IDENTITY_URL = "https://app.infisical.com/personal-settings/machine-identities"
+
+
+class InfisicalAcquirer(CredentialAcquirer):
+    kind = "infisical"
+    display_name = "Infisical machine identity (paste)"
+    # The captured credentials are how briar talks to Infisical itself
+    # — they cannot be stored INSIDE Infisical (chicken-and-egg). The
+    # CLI forces --store=envfile when this policy is set.
+    destination_policy = DestinationPolicy.BOOTSTRAP_LOCAL
+
+    def acquire(self, *, company: str, prompt: PromptIO) -> Credentials:
+        prompt.info("==> Infisical machine identity")
+        prompt.info("    This is the bootstrap step — once these three values land in your")
+        prompt.info("    local store, briar can subsequently use Infisical as a CredentialStore")
+        prompt.info("    (`briar auth login ... --store infisical`).")
+        prompt.info("")
+        prompt.info(f"    1. Open {_MACHINE_IDENTITY_URL}")
+        prompt.info("    2. Click 'Create Identity', name it `briar-cli`")
+        prompt.info("    3. Select 'Universal Auth' as the auth method → create")
+        prompt.info("    4. Open the new identity → 'Create Client Secret'")
+        prompt.info("    5. Add the identity to your project: project Settings → Access Control →")
+        prompt.info("       Machine Identities → Add identity → grant 'Secrets / Read' + 'Write'")
+        prompt.info("    6. Copy: Client ID + Client Secret (you only see the secret once) + Project ID")
+        prompt.open_url(_MACHINE_IDENTITY_URL)
+
+        client_id = prompt.prompt("    INFISICAL_CLIENT_ID (UUID): ").strip()
+        client_secret = prompt.prompt("    INFISICAL_CLIENT_SECRET: ", secret=True).strip()
+        project_id = prompt.prompt("    INFISICAL_PROJECT_ID (UUID, project Settings → General): ").strip()
+        env_slug = prompt.prompt("    INFISICAL_ENV slug [prod]: ").strip() or "prod"
+        host = prompt.prompt("    INFISICAL_HOST [https://app.infisical.com]: ").strip() or "https://app.infisical.com"
+
+        if not (client_id and client_secret and project_id):
+            raise ValueError("infisical: client_id + client_secret + project_id all required")
+
+        return Credentials(
+            provider_kind=self.kind,
+            entries={
+                "INFISICAL_CLIENT_ID": client_id,
+                "INFISICAL_CLIENT_SECRET": client_secret,
+                "INFISICAL_PROJECT_ID": project_id,
+                "INFISICAL_ENV": env_slug,
+                "INFISICAL_HOST": host,
+            },
+            metadata={"auth_mode": "universal-auth-machine-identity"},
+        )
+
+    @classmethod
+    def writes(cls, *, company: str) -> List[str]:
+        # The three required vars (env + host are listed in acquire() but
+        # not surfaced here — they're operational defaults the doctor
+        # doesn't need to flag as missing).
+        return ["INFISICAL_CLIENT_ID", "INFISICAL_CLIENT_SECRET", "INFISICAL_PROJECT_ID"]

briar/auth/_acquirers/jira_session.py

@@ -0,0 +1,102 @@
+"""Jira browser-session-cookie acquirer.
+
+Walks the user through DevTools cookie extraction. For tenants where
+the user cannot generate an API token (SSO policy, restricted
+account types).
+
+Stores ``JIRA_<COMPANY>_URL``, ``JIRA_<COMPANY>_TENANT_SESSION_TOKEN``,
+and sets ``JIRA_<COMPANY>_AUTH_KIND=session``. ``cloud.session.token``
++ ``atlassian.xsrf.token`` are accepted as optional extras.
+
+Parses the JWT payload to record ``expires_at`` so the CLI can warn
+about the upcoming rotation."""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from briar.auth._acquirer import CredentialAcquirer, Credentials
+from briar.auth._prompt import PromptIO
+from briar.env_vars import CredEnv
+
+
+log = logging.getLogger(__name__)
+
+
+def _decode_jwt_exp(jwt: str) -> Optional[datetime]:
+    """Return the ``exp`` claim as a tz-aware UTC datetime, or None
+    if the token isn't a 3-segment JWT or doesn't carry an exp.
+    Silently tolerates malformed segments — the cookie is the source
+    of truth; expiry detection is a nice-to-have."""
+    parts = jwt.split(".")
+    if len(parts) != 3:
+        return None
+    payload = parts[1]
+    padded = payload + "=" * (-len(payload) % 4)
+    try:
+        claims = json.loads(base64.urlsafe_b64decode(padded))
+    except Exception:  # noqa: BLE001
+        return None
+    exp = claims.get("exp")
+    if not isinstance(exp, int):
+        return None
+    return datetime.fromtimestamp(exp, tz=timezone.utc)
+
+
+class JiraSessionAcquirer(CredentialAcquirer):
+    kind = "jira-session"
+    display_name = "Jira browser session cookie (DevTools paste)"
+
+    def acquire(self, *, company: str, prompt: PromptIO) -> Credentials:
+        if not company:
+            raise ValueError("jira-session: --company is required")
+
+        prompt.info("==> Jira browser-session cookie")
+        prompt.info("    1. Log into your Jira tenant in the browser (https://<org>.atlassian.net)")
+        prompt.info("    2. DevTools → Application → Cookies → <your tenant>")
+        prompt.info("    3. Click the `tenant.session.token` row")
+        prompt.info("    4. DOUBLE-CLICK the Value cell and copy the full value (starts with `eyJ`)")
+        prompt.info("       (drag-selecting often truncates the start — use double-click)")
+
+        url = prompt.prompt("    Jira URL (https://<org>.atlassian.net): ").strip().rstrip("/")
+        tenant_token = prompt.prompt("    paste tenant.session.token: ", secret=True).strip()
+        cloud_token = prompt.prompt("    paste cloud.session.token (optional, ENTER to skip): ", secret=True).strip()
+        xsrf_token = prompt.prompt("    paste atlassian.xsrf.token (optional, ENTER to skip): ", secret=True).strip()
+
+        if not (url and tenant_token):
+            raise ValueError("jira-session: URL + tenant.session.token required (at minimum)")
+
+        entries = {
+            CredEnv.JIRA_URL.for_company(company): url,
+            CredEnv.JIRA_TENANT_SESSION_TOKEN.for_company(company): tenant_token,
+            CredEnv.JIRA_AUTH_KIND.for_company(company): "session",
+        }
+        if cloud_token:
+            entries[CredEnv.JIRA_SESSION_TOKEN.for_company(company)] = cloud_token
+        if xsrf_token:
+            entries[CredEnv.JIRA_XSRF_TOKEN.for_company(company)] = xsrf_token
+
+        expires_at = _decode_jwt_exp(tenant_token)
+        return Credentials(
+            provider_kind=self.kind,
+            entries=entries,
+            expires_at=expires_at,
+            metadata={"auth_mode": "browser-session"},
+        )
+
+    @classmethod
+    def writes(cls, *, company: str) -> List[str]:
+        if not company:
+            return []
+        # The mandatory writes; cloud/xsrf are optional and not listed
+        # (doctor reports them as nice-to-have via JiraSessionAuth's
+        # required_env_vars).
+        return [
+            CredEnv.JIRA_URL.for_company(company),
+            CredEnv.JIRA_TENANT_SESSION_TOKEN.for_company(company),
+            CredEnv.JIRA_AUTH_KIND.for_company(company),
+        ]